29
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 what he needs to know (and maybe a little more), but you don't want to overwhelm him with unneeded details.
If there are larger themes in a release, you might ...
18
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 contracts of the API and how its various components fit together -- how are you supposed to use this collection of classes and functions to write your ...
13
Start with the style guidelines from Oracle for Javadoc. While those guidelines are written for the Javadoc tool (and the Java language) in particular, the principles there apply to the corresponding tools for other languages. (I've seen this kind of documentation for C++, C#, and JavaScript APIs.) This answer augments that style guide.
I'm going to ...
13
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 feature come with an updated manual, and your users use the updated manuals, then there is little harm in pointing users towards features that are helpful, provided ...
13
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 people complaining about the absence of BETA features in PROD version.
Then, put less effort into BETA section if you intend to change it early and often (as ...
12
Python has a useful module called doctest. It is commonly used to validate tutorial documentation and examples embedded as comments in the code.
The doctest module searches for pieces of text that look like
interactive Python sessions, and then executes those sessions to
verify that they work exactly as shown. There are several common ways
to use ...
12
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 Microsoft Manual of Style specifies that literal elements like this should be written with their correct case. It also calls for using text styling to offset them, as ...
12
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 must admit most of the tips I will give will be my opinions and things I've found helpful. Below are some guidelines and design aspects you can use to help ...
11
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 are designed to keep your code as maintainable as possible, with an emphasis on readability.
There are a number of style guides you can follow. Here is Google'...
10
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 can be exploited to the detriment and possible losses of your clients, such a password sent using GET.
Despite license agreements that disclaim any and all ...
10
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. However, I think this is also somewhat dependent on why the numbers are appearing in your documentation.
If you are referencing these numbers as something would ...
10
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 would need a Content Management System (CMS) or authoring tool that has this type of functionality. You also need to consider how the information is delivered and ...
9
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 number in the version identifier, the Version. The releasing organization will change this number when there are major changes in the feature set of the ...
8
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 should be linked to other, relevant pages
Structure your pages like a tree, with overview pages nearer the root, providing more detail as you move towards the ...
8
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 Software Quality Process
As a formal deliverable to management or customers
As quality assurance measure
As an answer on Code Review Stack Exchange
As an ...
7
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 using a semantic markup already; if you're using a DTD/schema/tool/markdown that already has a notion of "keyboard input", you'd use that unless there's a good ...
7
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 in a column). This can be a straightforward HTML document with the supplementary descriptions as text.
If you need to produce E/R diagrams then Visio ...
7
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 formatting, and what organization they like.
As such, I think what's probably more important than what you choose as your method for formatting is how ...
7
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 there's extra or modified steps included. You'll lose the user along the way.
My long answer is that this is a also a good case of writers needing to push back ...
6
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 process. Anything related to UML would not be useful to them.
6
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 authoring environments, there are also ways to do this. My expertise is with DITA and in DITA you can use conditional processing attributes to tag content for ...
Only top voted, non community-wiki answers of a minimum length are eligible
