|Perl: the Markov chain saw|
Re: How to write documentation?by pjf (Curate)
|on Oct 18, 2001 at 13:56 UTC||Need Help??|
It sounds like you're already got a great start with the whole documentation thing. The following isn't really advice, it's more a relating of my own experience and what's worked for me.
For user documentation, I've found the best way is to get a user to write it. Seriously. There'll be things which neither yourself nor your fellow developers will think to document, simply because they're so obvious you'll never think of them. I've been at workplaces where the user documentation was always written by non-technical people for that very reason.
Documentation is like software in many ways, in that it also needs to be tested. The best people to test are those who aren't already familiar with the software, and haven't had you drop a previous copy of the user manual on their desk. I always exist my test population much too quickly. ;)
I try to document every function -- what it's purpose is, an y bugs or unexpected behaviour it might have, and an example of use if it's not immediately obvious. Good, clean code is often self-documenting, and that's certainly something worth aiming for.
Each file should also (at a minimum) have some header documentation stating the purpose of the file, when it was written, and who by. This means someone can quickly and easily find if they're in the right place without having to look at code.
Keeping an FAQ is also very useful. Usually the same questions keep appearing again and again. These are obviously things you want to document.