Lydia wrote to ask:
"I'm about to leave my first job working in a small office where I wrote macros to automate their work flow. Do you have any best practices for documentation?"
Documentation. One of the least understood parts of the job. And the one that is probably done more poorly than any other too.
That's because it's hard! I think it's often harder to write something that other people can read and understand than it is to write programs. Very often, the programmer is the least qualified to write the documentation. (After all, some programmers only can only communicate in grunts and hand gestures. Present company not included, of course!)
But because there is never enough time to really write great documentation, the first thing to do is prioritize the goals of your documentation. Do the most important parts first. Here's my list:
1 - The User Interface
One big reason this is high priority is that it's that part of your documentation that is most likely to be used. Make sure you cover:
- The goal of the program. The only other way some new person would be able to find out is by trial and error ... and more error ... and more error. Clearly describing what the program is for will save others tons of time and effort.
- How to start and end the program. (Especially if there is some additional task, like making a separate backup, that should be done.)
- Required information. There's nothing more frustrating than getting halfway through something and finding that you don't have some item of information necessary to finish it.
And if there is some unique little trick that someone using the program has to know, put it in a separate box to make it stand out. Here are some examples of tricks that some programs might need to illustrate what I mean:
"Make sure the number formatting of the selected cells is "Currency". Otherwise, you'll get the wrong answer."
"Never delete the bookmarks. They're required to put the information you supply in the right places."
2 - A System Diagram.
Show how the parts of the program fit together. This is important even if there's only one part. Someone completely new doesn't know there's only one part. People are visual creatures. There's real truth in the old saw, "A picture is worth a thousand words."
3 - Code documentation.
Last, and actually, "least" - detailed program documentation. Writing clear, commented and formatted code is the best program documentation. And most programmers I know are going to trust their own understanding of code rather than relying on anything you wrote anyway.
These are my ideas. If you have others, let me know about them.