29
I think that there is a very strong case to be made that this distinction between marketing voice and tech comm voice should be avoided entirely. There are two main reasons for this:
In ancient times, when tech comm and marketing were delivered on paper, each came to the customer at a different time and through a different channel. Generally they were done ...
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 ...
20
I wrote a whole book on this subject. It is called Every Page is Page One: Topic Based Writing for Technical Communication and the Web. In it I look at the research on how people use technical information and how the web changes how we use information generally and come up with seven principles for topic design.
One of the things I looked at in depth when ...
19
This is essentially a business problem, which is not to say it is off topic, because technical writers exist to solve business problems. But it is not a problem the writer should try to solve on their own. You have to get guidance from the product manager.
However, there is a very good chance that the product manager has not thought this through, so you ...
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
Arguments modify the behavior of a program. Running it without arguments means you get is default, unmodified behavior. So the help should describe the default unmodified behavior first, in the body of the description.
$ foo -h
foo [OPTIONS...]
Foo does X. For example:
foo
X happens.
To make foo do Y, use the -y option. For example:
foo -y
X ...
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 ...
7
The GNU site itself treats the name of the Make utility as an uppercased word: https://www.gnu.org/software/make/
There does seem to be a convention to frequently use make (the command) where Make (the name) would seem more appropriate. The GNU Make manual seems to do this almost exclusively (https://www.gnu.org/software/make/manual/make.html) but always ...
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 ...
6
People choose words to make distinctions. Sometimes the distinctions they are trying to make are fine-grained and sometimes they are not. In many cases, the people making the coarse-grained distinctions are not even aware that the fine-grained distinctions exist. People tend to choose the most familiar word that makes the distinction they are interested in ...
6
In this case I think what you want is if...else.
The slash tends to be used to suggest alternatives: yes/no answer. But you are talking about a case where both are present.
The hyphen is used to make a phrase into a word you can talk about. Instances have an is-a relationship to their class. But if and else are not consecutive words in these ...
Only top voted, non community-wiki answers of a minimum length are eligible
