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.
- Military Dress of the Peninsular War 1808-1814.
- The Chopped Cookbook: Use What Youve Got to Cook Something Great?
- The Art of Technical Documentation!
- ClickHelp - Innovative Software Documentation Tool.
- The Phantom Freighter (The Hardy Boys, Book 26)?
- The Mgmt of Technical Change - Automation in the UK, USA since 1950!
- The documentation challenge.
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. 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: Establishing the purpose of the document Assessing the audience Determining the scope Selecting the appropriate medium 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? The audience is members of the Perl Monks community. This community is focused on Perl. It's a diverse community with wide skill levels from complete novice to Perl gurus, but since this is a tutorial, I'm covering fairly basic material. It's a fairly friendly and informal place, so a conversational writing tone is appropriate.
The Art of Technical Documentation - Katherin Haramundanis - Google книги
What is the scope? This is an introductory tutorial. The purpose is not to turn each and every Perl Monk into a technical writer, but to give an overview of the documentation process. What is the medium? Perl Monks, of course! More generally, this tutorial is an online article presented on a web site. This is important: writing for the web is not the same as writing for print or any other media. What works well on paper may not work on the web.
The web also has features that print does not, such as the ability to link to more information. Use these features to the fullest. 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. 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.
- Artificial Muscles: Applications of Advanced Polymeric Nanocomposites?
- Principles of Technical Writing;
- Religion in Literature and Film in South Asia.
- Endocrine Secrets, Fourth Edition;
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.
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:. 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:. 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 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. Handbook of Technical Writing, 6th edition.
Sikora, Drew. The Art of Code Documentation. Game Dev. However I do have one small disagreement.
Basic guidelines to writing technical documentation
The article that you link to by Drew Sikora offers what I consider to be horrible advice on commenting. He obviously gives short shrift to the real issues with how commenting style ages as code is maintained. He also fails to appreciate the importance and value of making code definitive.
When you first write them your bug count in code and comments is approximately the same. But you catch errors in your code. You never see the ones in your comments. So if code and comment disagree as they will from time to time the code is rather more likely to be correct.