30
votes
Should software product release notes be in marketing voice or technical voice? (software documentation)
Release notes should describe what changed as seen by the users. That doesn't necessarily mean "all the gory technical details", though; as with other technical writing, you want to tell the user ...
- 21.3k
19
votes
Where do I start with C++ documentation?
What you write depends on your audience. API reference documentation -- the output of tool- like Doxygen -- is usually for the users of that API. Such externally-facing documentation focuses on the ...
- 21.3k
13
votes
Should beta functionality be mentioned in a training manual?
This is dependent upon how likely you are to publish a new training manual when the feature leaves beta.
If you are regularly updating your training materials, so that any changes to the beta ...
- 723
13
votes
Accepted
Should beta functionality be mentioned in a training manual?
I usually include a clearly marked "Beta Features" section. (either overall bundled together, or in individual sections marked as "BETA only").
This allows non-BETA users to skip it, and eliminates ...
- 570
12
votes
Accepted
Good Examples of and Practices in Code Documentation
Introduction
The Biggest reason documentation is written is to help developers learn about the software system and give them a reference to the tools they are using. This is a broad question and I ...
- 381
12
votes
Accepted
Starting a sentence with the name of a program or command-line tool: capitalization?
Rule #1 in technical documentation is: don't mislead the reader. If the command or function name begins with a lowercase letter, capitalizing it is an error -- it's not "Cat" but "cat". The ...
- 21.3k
12
votes
Where do I start with C++ documentation?
Find a style guide and stick with it.
Style guides are more than just comments - they cover all parts of your code from how you name your variables to how you structure your code. Good style guides ...
- 11.2k
10
votes
How should I document a product release with an inherently flawed design?
Absolutely document them and point them out to management.
As Mark says, this is a business problem. As a coder myself with forty years of commercial experience, your problem is that almost any flaw ...
- 93.3k
10
votes
Alternatives better to the binary "0b..." format?
As somewhat alluded to by Chenmunka, if your documentation is generally in the context of a specific programming language and/or compiler, it is probably best to stick to what is required by those. ...
- 725
10
votes
How to Document Systems with Different Versions?
What kind of software do you use for content development? I've found that branching is a good way to address version control if you have a need to support multiple versions simultaneously, but you ...
- 416
9
votes
Accepted
What are some standards in naming a software/hardware version?
I developed software for many decades for several organizations. The standards for versioning were varied, but there are some general guidelines that most of them followed.
I will call the leftmost ...
- 4,904
8
votes
Accepted
Format keyboard keys in documents
I am assuming that your organization does not have an official style guide, or that this is a personal project. (If you are bound by a style guide, consult it.) I am also assuming that you aren't ...
- 21.3k
8
votes
How should I document a database schema?
If this is user-facing documentation, then make up a data dictionary that describes the tables and columns with supplementary blurbs about the meaning of the data (e.g. the meanings of specific values ...
8
votes
Accepted
Methods for writing a code review
It depends on the context
Code reviews can be done for various reasons and the way to write one it heavily dependent on the purpose. Some of the reasons you might write a code review:
As part of a ...
- 4,068
7
votes
Accepted
Is markdown a good choice for large-scale, web-based software developer documentation?
In my experience, no matter what you do you will end up with variances and idiosyncrasies throughout your documentation. People have different expectations for what level of formality, what level of ...
- 725
7
votes
Is it better to repeat steps listed elsewhere in a manual, or to refer the reader to where the steps are listed elsewhere in the manual?
This is a close duplicate of Does DRY (Don't Repeat Yourself) Apply to Documentation?
My short answer is do what's right for the user, not yourself. That's probably repeating the code, especially if ...
- 389
7
votes
Structure for software documentation: long vs short pages
TL;DR
Short pages are better.
The Ideal Structure
I would recommend the following:
Each page should have a single, clearly defined purpose
Each pages should have a clearly defined audience
Pages ...
- 637
7
votes
Accepted
Where do I start with C++ documentation?
I am a professor and PhD that has been coding over 40 years. I'll restrict this comment to documenting code, which is different enough to warrant its own answer from a professional: I "grew up&...
- 93.3k
6
votes
Accepted
Are UML component diagrams helpful to non-technical users?
I think basic flow charts would work best here. If they are non-technical, they won't care what shapes or symbols you choose or be able to understand anything more than a general overview of the ...
- 516
6
votes
Accepted
How do I maintain effective documentation for different audiences while avoiding duplication?
I think this depends on the tools you're using to create the documentation. Doxygen has some manual commands you can use for conditions: http://www.doxygen.nl/manual/commands.html
In most structured ...
- 416
Only top scored, non community-wiki answers of a minimum length are eligible