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.
622
questions
0
votes
5
answers
233
views
Is there a term that describes the property of being synchronous vs asynchronous?
Is there a term that describes the property of being synchronous vs asynchronous?
The term that most naturally comes to mind is "synchronicity", however I only see this term being use in ...
- 119
4
votes
2
answers
267
views
Term for type information from C Source Code
I'm writing a code that extracts information about functions (prototype) and types (enum, struct, typedef) from a C source file.
This is to augment the type information about a particular function or ...
- 352
28
votes
6
answers
9k
views
Is documenting a big project with UML Diagrams needed, good to have or even not possible?
I developed a big(ger) project, which is in use already and grows, gets altered, fixed, etc. every week.
Until now I am the only developer. Since the team has to grow, also we will be more developers ...
- 409
1
vote
5
answers
110
views
Should docs of extended methods include documentation of the base method?
Let's say some method of a parent class is reimplemented in a child class.
This child method is intended to do the same that the parent method, with a minor change.
In this case, in the documentation ...
- 21
1
vote
2
answers
225
views
How to document pass-through parameters
I'm currently working with a pre-existing class (not written by me) that has functions which call other functions, passing through the parameters to the helper functions. Sometimes there are layers to ...
- 23
2
votes
3
answers
313
views
Documenting my abstract class/interface - what is important?
I am still an beginner/intermediate programmer at best so apologies if I misuse terminology.
I work with SCADA software for my job, specifically Ignition by Inductive Automation. It's made for rapid ...
4
votes
2
answers
399
views
Situation where software engineers effectively take role of product (unwanted, but for practical reasons)
My team owns several services. One is our primary focus: an accounts service. We have a plentiful stream of feature work and tech debt to address there, and everyone (engineers, product, design, ...
- 425
2
votes
2
answers
206
views
What's a good workflow for including mechanical sketches in code comments?
My team writes a lot of Python code in PyCharm to do quick simulations and calculations for our mechanical engineering work. Often, we'd like to include a little image (a hand drawn sketch, CAD ...
- 93
0
votes
2
answers
170
views
What does "legacy signature" mean?
I see the term legacy signature a lot in the documentation of programming languages. For example in the php documentation :
Passing the separator after the array (i.e. using the legacy signature) ...
-3
votes
1
answer
84
views
Technical Debt in frontend development [closed]
I have recently joined in a new company as a frontend developer and I got access to their current repository which is made in ReactJS. I can see that current team is not very experienced in reactJS ...
- 1
2
votes
2
answers
150
views
How to document external libraries that have been adopted into an existing codebase?
I have been using an external library for a while now. Unfortunately, it stopped receiving updates, and has since been adopted into my codebase.
The issue is the library was poorly documented in the ...
1
vote
0
answers
72
views
How sould I document dimensions of a pointed-to buffer?
This is a "doxygen style/etiquette" question.
I have a function which takes, say, an int *buffer. Now, buffer is actually a multi-dimensional array, with different dimensions in each axis, ...
- 2,489
1
vote
2
answers
336
views
How to document a NoSQL document-based data model?
How do you document the logical data model of a document-oriented database like MongoDB?
For relational databases, Entity-Relationship diagrams or UML class diagrams are used.
What is the practice for ...
- 71
0
votes
2
answers
160
views
How to automatically manage documentation
Our project consists of a cluster of microservices (let's say 20, mainly JS & PHP) that are communicating among themselves and exchanging data (via MQ) among themselves. Also, clusters have API ...
- 19
2
votes
1
answer
154
views
Is using the doxygen @file command counter-productive?
I'm having a dilemma regarding whether or not to use Doxygen's \@file (a.k.a. \file) command.
On the one hand, it's somewhat useful for you to use @file, and IIANM, Doxygen relies on its presence ...
- 2,489
-3
votes
1
answer
266
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....
- 151
3
votes
1
answer
323
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 ...
- 33
-2
votes
1
answer
72
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 ...
- 353
9
votes
4
answers
551
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 ...
- 209
0
votes
1
answer
223
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 ...
- 241
-1
votes
1
answer
50
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 ...
- 955
1
vote
1
answer
138
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 ...
- 231
4
votes
2
answers
139
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 ...
- 157
-2
votes
1
answer
51
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 ...
- 500
-1
votes
1
answer
55
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
1
answer
743
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 ...
- 119
43
votes
7
answers
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" ...
- 549
1
vote
2
answers
211
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 ...
- 113
-2
votes
1
answer
390
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 ...
- 2,489
24
votes
11
answers
7k
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 ...
- 349
1
vote
1
answer
105
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 ...
- 837
1
vote
1
answer
99
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 ...
- 143
1
vote
4
answers
2k
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 ...
- 23
-1
votes
4
answers
181
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
1
answer
101
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
...
- 137
2
votes
1
answer
148
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 ...
- 129
2
votes
4
answers
337
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 ...
- 241
0
votes
1
answer
83
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 ...
- 131
1
vote
1
answer
249
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 ...
- 179
3
votes
4
answers
1k
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" ...
- 367
-2
votes
1
answer
55
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 ...
- 307
12
votes
4
answers
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.
...
- 301
2
votes
1
answer
401
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
2
answers
191
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')
...
- 205
-1
votes
1
answer
114
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 ...
- 9
4
votes
3
answers
452
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 ...
- 241
-4
votes
3
answers
692
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
...
- 5
1
vote
2
answers
97
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 ...
- 163
16
votes
3
answers
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 ...
- 299
-3
votes
1
answer
88
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....
- 109