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.
643 questions
2
votes
1
answer
204
views
Software Requirement Specification document "Purpose section"
When we write the "Purpose" section of a SRS document, do we write:
The document purpose?
or
The Software to-be-built purpose?
I have checked some examples and it seems the first one but ...
- 319
2
votes
2
answers
195
views
How should the changelog be updated if a change is backported from a newer branch to an older one?
Suppose I am developing an application with the following versions currently available:
Latest stable: 1.3.0
Latest beta: 1.3.1
Latest alpha: 2.0.0
The project has a main branch for 2.x development ...
- 131
1
vote
1
answer
227
views
How to deal with outdated PowerShell and Azure PS in Azure Automation?
Azure Automation is a service for running scripts in the cloud, intended for the automation of administration tasks. While using it, I came across strangely outdated technologies being used under the ...
- 125
2
votes
2
answers
263
views
Correcting document errors in semantic versioning
Semantic versioning is a scheme of versioning that make the compatibility of different versions of a software component apparent to human and non-human agents.
In essence, when a backwards-compatible ...
- 374
2
votes
2
answers
294
views
In Java Interface contracts, does the @throws tag order should be considered?
Concrete example : https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/io/DataInput.html#readFully(byte[],int,int)
@throws NullPointerException if {@code b} is {@code null}.
is before
@...
- 131
10
votes
5
answers
4k
views
Writing public libraries: Should I let the consumer of the library enforce thread safety?
I'm writing a .NET library which exposes certain public APIs. Currently, I have not enforced thread safety in my library for following reasons apparent to me:
locks (Monitor.Enter and Monitor.Exit) ...
- 319
0
votes
1
answer
315
views
Creating necessary documentation for maintenance staff when only Code repository contents can be relied on
Conditions:
stable legacy prod system
no Software Devs of the system are available anymore
app is maintained by Engineers, who do not have the same software dev experience like the original Devs and ...
- 125
2
votes
2
answers
197
views
How to document a concurrent communication protocol for less theoretical people
We are developing a multi-user web-based application, where the users can join a "room" and a complicated handshake has to be set up between them, to be able to use a library on each ...
- 61
21
votes
6
answers
6k
views
What are better ways of indicating "insert actual value in place of the placeholder value" in documentation?
We develop an online booking system and it may be embedded in customer websites in an iframe. It is very simple to use, you just include a JavaScript file on the page and call the initialisation ...
- 379
1
vote
1
answer
597
views
Should I include an actor to represent the database in a use case diagram? [duplicate]
I'm working on the documentation of software management system. That system can be linked with an e-commerce website to get financial data directly. For example when a transaction will be made it will ...
- 21
-1
votes
2
answers
87
views
Java: Autogenerating documentation for Strategy Pattern with lambdas
Situation
Object MyObject needs to be sent to one of our downstream systems depending on the enum value of its field myField.
public class MyObject {
private MyEnum myField;
public MyEnum ...
- 99
4
votes
2
answers
295
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 ...
- 377
1
vote
5
answers
167
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
3
votes
3
answers
1k
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 ...
3
votes
2
answers
318
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 ...
- 213
-3
votes
1
answer
160
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
1
vote
0
answers
77
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,808
0
votes
2
answers
306
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
-3
votes
1
answer
932
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....
- 141
-2
votes
1
answer
132
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 ...
- 413
0
votes
1
answer
1k
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 ...
- 261
1
vote
1
answer
238
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 ...
- 269
-2
votes
1
answer
306
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 ...
- 510
2
votes
1
answer
2k
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 ...
- 129
1
vote
2
answers
559
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