Questions tagged [documentation]

Software documentation is written text that accompanies computer software. It explains how the software operates, how to install it, how to use it, and other resources for help.

Filter by
Sorted by
Tagged with
-2
votes
0answers
25 views

How to document business processes/rules inside Python code and export them?

I'm in a project that computes a lot of metrics with Python code. We need to document how each metric is computed, inside the code, for readability, and outside, in some Wiki, for non-technical people....
3
votes
1answer
84 views

UML activity diagram modeling for multiple input/output Program

I have to create a overview documentation for a simple PLC (programmable logic controller aka industrial automation controller) program (happens to be written in Step 7 but not really important). The ...
-2
votes
1answer
60 views

Do I need to write Scenarios if I use Event Storming? [closed]

Event Storming is a great method to understand the business processes. Scenario (Use Case Specification) also describes the business process. They both do one thing. But when documenting, the Event ...
8
votes
4answers
516 views

How to document alternative code I considered but didn't go with due to performance?

I write code in R, and often find myself attempting to optimize the code for better performance. In a given script that tackles a specific problem, I test different code alternatives and compare them ...
0
votes
1answer
57 views

Documenting classes with doxygen (I want a birds eye view of the code but also want documentation)

When I code in plain C there is quite a beautiful interaction between headers and c files in terms of documenting the code. I tend to add the documentation on the cc files (and yes I am aware that ...
-1
votes
1answer
45 views

What is the name of the documents that describes changes and implementation?

In our development process, we have documents for each task/feature that describe API changes API logic Data flow (if needed) Database changes How client should interact with new/modified APIs Other ...
1
vote
1answer
67 views

Given-when-then template for docstrings

Tests can be very nicely written down using the given-when-then style. Are there similar styles / templates for describing methods and classes in docstrings? To clarify: There are many sites which ...
0
votes
2answers
64 views

Documenting dynamic constraints in API data

Background I work for a company that provides installation instructions for solar panels on roofs. We also provide an API where external parties can provide roof input and preferences, and return an ...
-2
votes
1answer
37 views

What is the proper diagram to describe an event subscriber final graph?

I'm working on a microservice application and I need to describe the complete execution graph of a specific event being published, where each node in the graph is a specific microservice subscription ...
-1
votes
1answer
51 views

Writing Release Notes for gradual feature rollout

Our software product is not complete, but it is functional enough that one of our clients is using it. We produce release notes with every sprint. The notes are divided into sections such as "New ...
1
vote
1answer
302 views

How can I write good Conventional Commit-style commit messages for one feature over multiple commits?

If I am working on a single feature, I would usually commit multiple commits. Should every commit start with feat? Or should only 1 commit have the type of feat and use a different type for the other ...
43
votes
7answers
10k views

Should a rookie hint be mentioned in the documentation or not?

I was invited to review some code. I've never done that before and barely know the project. Thus I'm following the README step by step. I log everything. The README says in its "Quickstart" ...
1
vote
2answers
110 views

Is using KDoc/Javadoc comments inside of a function considered bad practice?

I often find it helpful to use KDoc/Javadoc comments inside of a class or function instead of normal comments. IntelliJ colorizes them more obviously by default and, more importantly, allows ...
-2
votes
1answer
88 views

How should I list authors and their roles in doxygen comments?

Suppose I'm the first person write a proper Doxygen comment for a source file. Suppose also that there have been multiple contributors to the file - original author, previous maintainers, current ...
24
votes
11answers
6k views

The Don't Repeat Yourself (DRY) principle in documentation

Dave Thomas, the author of the Don't Repeat Yourself principle said: DRY says that every piece of system knowledge should have one authoritative, unambiguous representation. Every piece of knowledge ...
1
vote
1answer
103 views

Where would you place the working description for a function?

i like to think out a function using comments before writing it. I'd like to keep the information in the code as comments somewhere but i don't know where it should be kept. At the moment i keep it at ...
1
vote
1answer
60 views

Use case descriptions -- where does selection go?

I have a use case for which a user can perform a multiselection. I am writing the use case description and wonder: Should the selection action be documented as a trigger of the use case, or in the ...
1
vote
4answers
346 views

Is it good practice to put comment headers into each file?

I have an Unity project with countless of C# script files and I'm working on it solely. Although nobody else is working on it, I'm aware that some form of code documentation is crucial for my future ...
-1
votes
4answers
172 views

What is the Software Engineering equivalent of a traditional Engineering Change Order (ECO)? [closed]

What best practices do large software companies recommend when introducing a breaking-change to their software development process? Put another way, how do you best communicate these changes to fellow ...
0
votes
1answer
89 views

Code reference symbols in documentation, comments and pull requests?

I've seen method references in PRs and comments and documentation but it's unclear what the specific symbology means. E.g. ClassName#myMethod or ClassName::myMethod or what about ClassName::CONSTANT ...
2
votes
1answer
101 views

What types of documents should I include in a legacy software documentation package?

TL;DR: What would you look for in a collection of documentation when taking over an app to be run a larger scale than originally designed for? I've been tasked with writing documentation for an ...
2
votes
4answers
163 views

How can I keep track of which existing lines of code/text have passed some new review?

Firstly, this is a really tough topic to do searches for because you get a wealth of information on “code review”, which is different from what I’m referring to here. That normally refers to ...
0
votes
1answer
44 views

How to document attributes from legacy application

I have to replace an old application (Database, C++ UI) which is mainly for data administration, with on a new application (Same Database, Spring-Boot, Angular). We want to document how the ...
0
votes
1answer
89 views

Managing Documentation / Source Control for a Full-Stack Application Across Multiple Repos

TL;DR I have a moderately sized/complexity web application (Angular 11) in one repo and a standalone REST API (.NET Core 3 / C#) in another repo, and am trying to figure out the most efficient way to ...
0
votes
0answers
55 views

Open API documentation in function definition? - YAML verbatim vs JavaDoc

Open API [swagger] is a fancy way of writing REST API documentation, it looks like: description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/...
2
votes
2answers
265 views

If logging in is not a Use Case, then what is it and where do I describe it?

I am writing a functional specification for a project and I wish to express the expected system behaviour in Use Cases. I have read a bunch of opposing opinions on whether "logging in" ...
-2
votes
1answer
52 views

How do you enforce API contracts across mutliple stacks?

For systems that are built on top of diverse tech stacks, including both static and dynamic types languages, what is in practice some ways to have the API contracts published and enforced? Some wiki ...
12
votes
4answers
1k views

What is the meaning of the quote: "A bug in the code is worth two in the documentation."?

As I boot up Eclipse for C++ with the "Darkest Dark Theme with DevStyle" installed, it spits out quotes--one per day. Yesterday's was: A bug in the code is worth two in the documentation. ...
2
votes
1answer
211 views

AMQP messaging: How to generate documentation for consumers?

My application publishes various messages (e.g., telemetry, changed-events, ...) to a RabbitMQ message-broker. The users have no access to the source-code and therefore, will need a separate ...
0
votes
2answers
187 views

Errors that don't make code behave wrong from user's point of view - how would you call them?

var file_extension = 'txt'; if (file_extension === 'txt') alert('plain text'); else if (file_extension === 'md') alert('markdown'); var file_extension = 'txt'; if (file_extension === 'txt') ...
-1
votes
1answer
85 views

How should I document a higher-order Python function?

I'm interested in designing a high level function in Python, (I.E. a function that takes other functions as arguments) but I don't know of any good conventions for documenting such a function. For ...
4
votes
3answers
345 views

How to visualize a Stream object (and some other data types)?

I want to make a small programming tutorial which will have a number of images visualizing various data types, but I am not sure how to draw these images of the data types. Assume that I have a ...
-4
votes
3answers
323 views

Documenting a project in a README.md and in a Wiki page?

I work on both frontend and backend applications and I still wonder how to document those applications. When we start a development, we usually : Start a README.md that describes the application ...
1
vote
2answers
76 views

How to write documentation for CLI app that requires stdin?

I am writing CLI program that can accept very long strings. For this reason I decided to pipe the data into the program as I would hit limitation of the shell / OS. How should these CLI program ...
16
votes
3answers
2k views

When to add version numbers to documentation

It is often useful to document when (i.e. in which versions) a feature was added, marked as deprecated, etc. For example: Function FooBar(x, y, z) Foos x with y and bars them with z. (Parameter z was ...
-3
votes
1answer
85 views

In Java API documentation, what does it mean to inherit an abstract method? [closed]

Here's an example: In the documentation for java.util.HashSet, there's a list of "Methods inherited from interface java.util.Set", including equals, which is an abstract method in java.util....
-5
votes
1answer
82 views

Giving a fixed project price when REST is involved

Whenever I am asked to give a quote for a project that involves a remote REST API, I become very cautious. Most of the REST API's I worked with had a documentation, but it usually turned out to be ...
37
votes
8answers
11k views

Literate programming vs reasonably documenting your code

In a project that aspires from the onset to be maintainable across a revolving team of developers, what difference would it make to use literate programming against thorough commenting guidelines? The ...
-1
votes
1answer
774 views

Does the intrinsics functions from Intel Instrinsics Guide also works on AMD CPUs?

The link bellow is the Intel Instrinsics Guide for intrinsics functions. (SSE, AVX, etc.) https://software.intel.com/sites/landingpage/IntrinsicsGuide/# Does this functions also works on a AMD CPU, ...
4
votes
4answers
219 views

How to describe a function argument that is used as a hint/best-effort?

Say I have a server exposing an api that let me retrieve 'things', there are a lot of things, and as such retrieving all things at once could take down the server, hence the exposed API returns ...
0
votes
2answers
194 views

Do we draw the dataset as a secondary actor in a use case diagram?

I am working on a project to detect cancer and I am using deep learning (Convolutional neural network). In the user interface, the user has only to input an image number then click test when the user ...
-2
votes
2answers
122 views

Architecture of new software documentation

My question is related to designing new software. Let's say I work in a medium-sized company that has a core product. Now we want to start with new software (purpose of the application is different ...
2
votes
4answers
126 views

How do I write, review and coach better English language in documentation?

My job regularly involves writing and reviewing (in the form of pull requests) English prose in the documentation for our internal system, which solely faces other developers, in a strongly American ...
1
vote
1answer
65 views

How to improve readability of a specification document containing lots of tables?

We maintain a technical project whose specifications are in a document of few hundred pages. It's a text document (Word), not a Wiki or a Web-based stuff. The document contains lots of tables with ...
2
votes
1answer
357 views

In what file do I put the installation steps in my git repository?

I have a git repository and I would like to add the installation steps required to make the project work locally. The project is a company and private project and users will also be contributors. I'm ...
1
vote
2answers
667 views

How to structure the project documentation?

I just started our bachelor thesis, and want to ask you how to make a proper documentation. There are two pieces of software in our project's scope: a microcontroller software (node), and a server ...
9
votes
2answers
350 views

How should I make it less scary for a team to create diagrams?

Context I am a strong proponent of clear, illustrative diagrams in documentation. When they are properly done, they improve a lot two aspects: the understanding of the documentation and the time a ...
-2
votes
2answers
127 views

How to document pitfalls and gotchas in the code base?

What are some ways of documenting pitfalls and gotchas when working with a codebase with a team of developers? I'm working with a team of developers on a big codebase and there's lots of small little ...
2
votes
4answers
252 views

How to deliver fast and avoid growth challenges with a codebase?

Startup Context A friend of mine recently asked me to be a part time software engineer for her startup which has yet to write any code. She is fairly serious and has already raised a fair bit of ...
5
votes
2answers
235 views

Testable documentation

I'm creating a library, and I would like to provide a tutorial on how to use the library. Such a tutorial will contain code snippets as usage examples; therefore, I would like to test these snippets ...

1
2 3 4 5
13