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
201
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
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
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
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
4
votes
4
answers
459
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
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
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
293
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
218
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
347
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
355
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* ...
- 643
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
-2
votes
1
answer
145
views
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
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
24
votes
11
answers
8k
views
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
1
vote
1
answer
595
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
0
votes
1
answer
221
views
Where to keep assets for documentation generation as to not clutter the main repository
I have a large C++ project I'm hoping to release publicly soon (it is currently an internal development at work).
We have a large auto documentation setup which uses doxygen and sphinx, however our ...
- 109
-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
2
votes
7
answers
777
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 ...
- 139
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
28
votes
6
answers
11k
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
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
1
vote
2
answers
1k
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 ...
- 123
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 ...
4
votes
2
answers
573
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, ...
- 471
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
1
vote
2
answers
308
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
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
2
votes
2
answers
249
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
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
1
vote
2
answers
2k
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
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
1k
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:
/**
* @file my_filename.c
*
* etc. etc.
On the one hand, it's somewhat useful for you to use @file, ...
- 2,808
-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
3
votes
1
answer
2k
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
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
9
votes
4
answers
663
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
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
votes
1
answer
357
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 ...
- 975
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
4
votes
2
answers
183
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
304
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
-1
votes
1
answer
119
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 ...
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
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" ...
- 545
1
vote
2
answers
558
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
1k
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,808