Re: Our documentation sucks

There are a few problems with documentation. Here are a few that I see coming up time and time again:

You need to know the audience for the documentation. Sometimes, it's better to write more than one set of documentation, rather than try to write for multiple audiences in one document. (eg, first time users, more advanced users, future maintainers, etc.)
Code maintainers are too close to the problem. Because they know the system intimately, it may be difficult for them to explain it to a newcomer without using jargon. The more complex a problem the program is trying to solve, the more likely this will happen.
Using jargon or concepts without explaining them. This might be fine for advanced users, but when you use terms that aren't understood by the audience, they're not going to be happy with the documentation. If it's a completely unfamiliar term, the person can quickly realize it's something they need to look up; if it's a term that's being used in uncommon ways, it may confuse the reader. (and what if it's just a uncommon usage for some audiences?)

Anyway, I propose the following -- keep two sets of documentation. Think of the first one like an API -- what the program is expected to do. You can even write this one before writing any code. The second set of documentation is for the code maintainers and/or advanced users, and needs to be updated whenever the code is. (the other may not need to change every time). Each set of documentation should contain a reference to the other one.

When people complain about the documentation, and it's something that's not there, you have to ask yourself why they didn't find the relevent section -- look at the terms they used to describe their issue, and the terms used within the actual documentation. Yes, there are some lazy users out there, but if you dismiss every user as a dumbass, you'll never improve the documentation. (and hopefully, better documentation means fewer people bugging you with stupid questions)

Update: I agree with j3 on non-pod comments for the maintainers ... I'm still not sure where the best place is for docs for advanced users. ... But with the mention of cookbooks I wanted to mention something else -- anything that goes into a cookbook should have a test made for it. (so that you can make sure you don't break your cookbook examples down the road). Is there a market for a script to generate cookbook files from tests or visa versa? (or generate them both from something else?)

Oh -- and as for the design doc -- I tend to keep an 'overview' doc that explains what the general goals of the project are, and a timeline of major feature additions, and major features that we're considering. It tends to be a more executive level document, to justify our project's funding, though. Something similar might be useful for other audiences, though.

Comment on Re: Our documentation sucks

Replies are listed 'Best First'.
Re^2: Our documentation sucks by j3 (Friar) on Apr 13, 2007 at 15:15 UTC
I agree jhourcle, but just to make things more concrete: The docs for your module's users go in your module's POD. I like xdg's suggestion of including a separate cookbook.pod as well. A tutorial.pod can be included too (since the main module's POD is sometimes more of a user's reference manual than a tutorial). The docs for maintainers (or advanced users who might want to tinker) just go into the code as regular comments, since maintainers will already be looking at the code anyway. And actually, there's a third kind of documentation that you might provide: A design doc. This can go in a separate design.pod file. I think of it this way: As a new user, I'll read the tutorial to learn to use the module. As a novice, I'll use the cookbook and reference manual as-needed. As an advanced user, I'll dig into the module's code and will be grateful to read the comments therein. As any of the above I might want to read the design doc to get a better idea of how the module was put together (which objects/functions use which), why you made the design choices you did, how I might go about extending it (say, with a plug-in), etc.	[reply]

Replies are listed 'Best First'.

Re^2: Our documentation sucks
by j3 (Friar) on Apr 13, 2007 at 15:15 UTC

I agree jhourcle, but just to make things more concrete:

The docs for your module's users go in your module's POD. I like xdg's suggestion of including a separate cookbook.pod as well. A tutorial.pod can be included too (since the main module's POD is sometimes more of a user's reference manual than a tutorial).
The docs for maintainers (or advanced users who might want to tinker) just go into the code as regular comments, since maintainers will already be looking at the code anyway.

And actually, there's a third kind of documentation that you might provide: A design doc. This can go in a separate design.pod file.

I think of it this way:

As a new user, I'll read the tutorial to learn to use the module.
As a novice, I'll use the cookbook and reference manual as-needed.
As an advanced user, I'll dig into the module's code and will be grateful to read the comments therein.
As any of the above I might want to read the design doc to get a better idea of how the module was put together (which objects/functions use which), why you made the design choices you did, how I might go about extending it (say, with a plug-in), etc.

[reply]