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 ...
user avatar
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 ...
user avatar
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 ...
user avatar
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 ...
user avatar
  • 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 ...
user avatar
  • 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 ...
user avatar
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 ...
user avatar
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 ...
user avatar
  • 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. ...
user avatar
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 ...
user avatar
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 ...
user avatar
  • 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 ...
user avatar
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 ...
user avatar
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 ...
user avatar
  • 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 ...
user avatar
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 ...
user avatar
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 ...
user avatar
  • 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&...
user avatar
  • 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 ...
user avatar
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 ...
user avatar

Only top scored, non community-wiki answers of a minimum length are eligible