Any good guides to give to developers for documentation?

Question

I've got to prepare a documentation guide for developers of a software project. We use a variety of languages (PHP and Java). I'm looking for some sort of language agnostic, high level, "this is what (or why) you should document" guide. Some heuristics and rules of thumbs that I can give to people to read in the hope that they will produce better documentation.

Answer 1

I believe there's no such thing as generic documentations for all methodologies. You probably have chosen one already. Each methodology has a set of recommended documentations, and these are usually language agnostic.

If you haven't chosen a methodology yet, IMHO this should be done before worrying about documentation guidelines.

However, if you want generic documentation info, you could check the wikipedia entry on the subject.

Answer 2

Key things to document:

• Functional specification so all stakeholders can see what they are supposed to be developing.

• Architecture overview so people can see where to look for particular functionality in the code base

Comments should have some high level breaks to show major points or sections of interest. They can be useful for visually breaking up the code to make it easier to navigate. For example, even if it doesn't contain much useful information, a banner comment on procedure/method definitions provides a visual cue that helps show the structure of a file and makes it quicker to navigate. However, over-commenting the code can bury this structure.

The real strength of comments is in more detailed discussion of non-obvious items. Some examples of this type of item are:

• Reasons for design decisions - why did we do it this way.

• Noting workarounds or other reasons for doing specific things - particularlty where there is some system-related issue that maintenance programmers should be aware of.

• Referring readers to other related items.

• Underlying business logic or interesting corner cases.

• Notes about the origin or meaning of data in certain variables or parameters where this is interesting. For example, if a variable might refer to a policy number or a dummy value then a note explaining the presence and origin of the dummy entry may add clarity.

Explaining a variable:

char *policy_no /* Customer ID Number */

doesn't really add value, but something like:

char *policy_no    /* Sometimes policy_no is null because inwards risk<br> 
                      references are not booked on M&D premiums */

Tells us something useful about the variable and what circumstances certain values might be expected.

Answer 3

When it comes to APIs and their documentation (JavaDocs and the equivalents in other languages), the rule should be:

• Design the API as if 80% of people will NEVER read the documentation for a method that they call. Therefore - attempt to follow the principle of least surprise.

• Assume that most of the other 20% will only skim it. If there is something critical that the user should know (e.g., do X first, don't do Y), make sure it is very very visible to someone skimming. Any trick, including making it a separate line or even using all-caps is legitimate.

The reason for this behavior is that as developers we are inherently lazy and optimistic. If we see a class and a method that seems to fit what we want, we're quite content to assume that it delivers on what we expect. In fact, the more intuitive a call is (clear name and no or few parametes vs. old win-api style monsters) the less incentive we have to bother and read its documentation.

See also my reply to "tips for writing great javadocs", or the information from my homepage.

Also, in general you need to pick between two philosophies: traditional documentation and agile/lean documentation. It is much easier to get developers to produce and use the latter (since less investment is required for writing and reading "only the important stuff"). However, the "important stuff" is subjective, so you risk losing some critical information. In addition, depending on your industry, you may be required to produce traditional documentation and specifications.

Answer 4

I think that how you document isn't as much of a concern as long as you're doing it in a way that works for you and you're consistent in how you do it. After all, people can adapt to something that's consistently wrong much better than they can adapt to something that's inconsistently right.

The only piece of advice that I have is to use doctests if your platform supports them. They can be tremendously helpful at finding inaccurate documentation.