|Welcome to the Monastery|
The basic principle of technical writing is simple: Tell them what you're going to tell them. Tell them. Then, tell them what you've told them.
Why am I telling you this? Because, like it or not, documentation is part of programming. Good documentation will make your life substantially easier. Consider this - even if you know your code inside and out without documentation, others may not. Would you prefer that every user pester you with questions, or that your documentation take care of that, leaving you time to code in peace?
This tutorial isn't going to focus on documenting code on a line-by-line basis, or on POD ("Plain Old Documentation"), but rather on the larger picture of how documentation is prepared. Its purpose is not to turn each and every Perl Monk into a technical writer, but rather to give you (the coder) an idea of how documentation is produced.
Obviously, if you're the only person working on a project, it's unlikely you'll hire a technical writer to create in depth documentation. In such a case, you'll end up doing the documentation yourself. If you work in an environment in which documentation is farmed out to a technical writer, don't think you're off the hook. Think of this tutorial as How to Get Along with your Technical Writer 101.
Principles of Technical Writing
The Handbook of Technical Writing, 6th edition (Alred et al), lists five steps to successful technical writing:
In the next few sections I will go through these steps in more detail, with an eye to highlighting points particularly relevant to software documentation.
Writing requires preparation. You can think of this step as being broken down into four tasks:
Let's look at this document. Before I sat down to write this tutorial, I asked myself some questions.
What is the purpose of the tutorial?
Who is the audience and what do I know about them?
What is the scope?
What is the medium?
The purpose of documentation is to convey information. In order to convey information, you must understand it. In this case we are talking about your code, so hopefully you understand it - but can you explain it?
If you have worked with a technical writer, you have undoubtedly faced a barrage of questions. "What does this do?" "What does that do?" "How does one...?" This is research. It is necessary. You can help it along by commenting your code. The expertise of technical writers varies widely. Some are expert coders themselves. Others may not have expertise beyond their tools of the trade. In any case, having comments in your code will help their research and reduce the amount of time they spend pestering you.
How should you comment your code? In The Art of Code Documentation Drew Sikora distinguishes between commenting for developers and commenting a finished program. When your code is still being developed, it is likely being read only by other developers. In this case, simple comments are fine. When code is finished, comments should be expanded into documentation so that users or future developers can get up to speed with what you were thinking when you were developing the program.
If you are not working with a technical writer, you will need to take on more of the research. You may understand your code, but do you understand how the modules used in your code work? What will users of your program need to know about what the program does? Keep in mind the answers to your questions from the preparation stage.
Poorly organized documentation may in fact be worse than no documentation. Consider what you need to tell users, and how that information can best be conveyed. For example, if you're writing installation instructions for a program, you will want to go with a sequential method of development: step 1, step 2, and so on. If you're writing a history of versions, use a chronological method of development. Choose the method that best suits your subject, your readers, and your purpose.
In software, often used methods of development are division and classification (explain each parts function and how the parts work together) and general-to-specific. In general-to-specific development, you begin with general information about the function of the software, and move to more specific information.
Once you've decided on an organization scheme, prepare an outline. This provides a road map for your writing. How you outline is a personal choice. Personally, I use an iterative approach: I start with a very broad outline, such as
Technical Writing/Documentation Tutorial Introduction Principles of Technical Writing Preparation Research Organization Draft Revision Conclusion References
I then go through my outline and break categories into sub-categories and sub-sub-categories until I feel I have a clear enough map. For example, I broke the Preparation category up in this manner:
Writing a Draft
Once you have your outline, you can begin writing. Expand your outline into paragraphs. Some advise not worrying about matters such as grammar, spelling, punctuation, and layout at this point. Personally, I find it difficult to follow this advice. I usually write fairly polished drafts. Regardless of your tactic, you will be revising your work in the next step.
You may wish to save the introduction for last, since you will have a better idea of what is covered in the body of the document. You will also need to write a conclusion to your document - remember the basic rule of technical writing:
Tell them what you're going to tell them. (Introduction)
RevisionRevision is one of the longest steps of this process. In my technical writing text, there's a checklist for all five steps of the writing process. The first four fit on the first page, and revision takes up a page of its own. When revising, check for completeness and accuracy. Check that your writing is concise, and covers a topic clearly. Check your spelling and grammar. Use spell check, but don't use it as a substitute for proof-reading. Review the mechanics: are abbreviations, acronyms, and initialisms expanded at their first usage? Don't do your revision in one step. I'm sure many of you have had the experience of spending hours looking for a bug in your code. You give up, frustrated, and the next day come back to see the problem staring out at you, as if in boldface. Likewise, having someone proofread your work is a good idea. How many times have you been frustrated by a bug and posted it on Perl Monks, only to get a quick response from someone else pointing out the problem? The same thing works for revision.
You may regard documentation as a chore. You may regard it as an opportunity to learn. Regardless, you do need to document your code. In this tutorial, I've presented the steps used in technical writing/documentation: preparation, research, organization, writing, and revision.
In preparation, key points discussed were: establishing the purpose, assessing the audience, determining the scope, and selecting the appropriate medium. The research section covered the reasons for research and strategies for commenting code. In organization, methods of development used in software documentation were introduced: sequential, chronological, division and classification, and general-to-specific. Outlining was also discussed. Finally, strategies for writing and revision were covered.
Aldred, Gerald J. et al, 2000. Handbook of Technical Writing, 6th edition. Boston: Bedford/St. Martin's.
Sikora, Drew. The Art of Code Documentation. Game Dev. http://www.gamedev.net/reference/programming/features/codedoc/