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.
640 questions
1vote
1answer
67views
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,646
1vote
1answer
104views
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
4votes
4answers
393views
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 ...
- 1,559
2votes
2answers
191views
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 ...
- 307
31votes
15answers
6kviews
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 ...
- 439
1vote
2answers
249views
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 @...
- 121
-2votes
1answer
190views
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
10votes
5answers
4kviews
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) ...
1vote
2answers
283views
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 ...
0votes
1answer
222views
Creating necessary documentation for maintenance staff when only Code repository contents can be relied on [closed]
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
1vote
2answers
267views
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* ...
- 643
2votes
2answers
179views
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
-2votes
1answer
137views
What is standard/considered best practice for the media used for different documentation? [closed]
I have just started my first position as a software engineer after finishing my degree, and, as warned, software is much different in industry than in academia. The startup that hired me does not have ...
- 107
21votes
6answers
6kviews
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 ...
24votes
11answers
8kviews
Why and how to write clear code comments and when will documentations be needed beyond code commenting?
I am learning programming on my own following standard programming language textbooks. I come from a math background. I learned C on my own, but never really got to the more advanced portions. I ...
- 381
