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

1. 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.)
2. 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.
3. 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.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.