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
206
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
15
votes
6
answers
2k
views
In an enterprise software team, is it recommended for developers to maintain a business knowledge wiki to understand domain concepts and processes?
I work in an enterprise software team, and I’m exploring ways to help developers better understand the business domain, company processes, and organizational knowledge beyond just technical ...
- 795
2
votes
2
answers
197
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
84
views
Is there an idiom for specifying axes and dimensions of array(-like) parameters? [closed]
Many programming languages have functions which take a parameter which is a potentially-multi-dimensional array, where the number of axes and the dimension in each axis is not specified in code. This ...
- 2,808
1
vote
1
answer
232
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
4
votes
4
answers
462
views
Documenting properties
Suppose I have a property with an associated getter and setter (the property is not exposed directly)
Where should I describe the property?
The field javadoc
The getter javadoc
The setter javadoc
...
- 2,030
2
votes
2
answers
264
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
33
votes
15
answers
6k
views
Using "iff" in documentation [closed]
Is the term "iff" (as an abbreviation in "If and only if") commonly understood, when used in software documentation? I thought so, but recently a colleague had not heard about it ...
- 459
2
votes
2
answers
300
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
-2
votes
1
answer
219
views
Do large companies like Facebook, Google, Netflix, etc., have internal documentation for their frontend and backend codebases? [closed]
I work at a fairly large startup/company of about 1000 people, a fraction of which are software engineers. We have some docs of various kinds, but the codebase isn't documented. Let me elaborate.
Here ...
- 11
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
1
vote
2
answers
352
views
Is there some standard or virtually standard way to document code in a language agnostic and IDE agnostic fashion? [closed]
In java we generally do it the java-docs way and in js the popular method these days is vscode documentation using @param, @returns, @example etc but I would prefer if there were some language ...
- 41
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
1
vote
2
answers
360
views
What is an appropriate length for function names? [closed]
I'm writing a C++ class, CBookSpellDef which has the following methods:
int GetIndexOf(const char *psz);
char* GetNameAtIndex(int index) { return m_spellTypes[index].szName; }
char* ...
- 641
2
votes
2
answers
200
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