Developing technical documentation
In a perfect world, every development team has one or more technical writers working alongside them to ensure quality documentation is available for their product. However, not all companies see the inherent value in technical writers, or perhaps you're working with a small group that cannot afford the extra expense. Regardless of the reason, you should keep a number of things in mind if you must develop your own documentation along with your software.
Needs analysis
The first thing most technical writers do is called a needs analysis, which can be split into two vital parts: audience analysis and task analysis.
Audience analysis
In audience analysis, you identify as specifically as possible who will be reading this documentation. Are you documenting your Application Programming Interface (API) for other development teams within the company? How about other developers outside the company? There is a huge difference between the two in terms of what you can assume the audience knows about your internal processes and what company data you can share and what you cannot.
Perhaps you're writing documentation for the end user. Are your users typically computer-savvy? Novices? Do you have a wide range of user types and backgrounds? If you're not sure, there are a few ways to find out. Talk to the help desk or technical support staff to find out their experiences with your user base. Read newsgroups and mailing lists dedicated to your product or similar products. You can even place a survey on your Web site or send out brief questionnaires to registered users. If you do this, make it clear what's in it for them—better documentation for their use—so they'll respond.
Task analysis
Task analysis involves determining how the reader will actually use this documentation. Are you preparing instructions on how to install your package? If so, then you'll want to focus on the step-by-step actions required to accomplish the installation. Are you detailing, as mentioned earlier, your API so other programmers can properly interface their products with yours? In this case, you probably want a reference format, where you've broken down the API components into some form of logical, top-down arrangement that will make it simple for another developer to find what he or she is looking for.
Sometimes a mix of the task and reference approaches is best, instead. Reference sections can be mentioned in the instructions and included as separate appendices. Other methods of accomplishing the mix and match involve tips, warnings, notes, tables, figures, and other elements that allow you to call the reader's attention to particular issues without making the write-up too clunky or dense.
Graphic elements
It's important to set apart such features as warnings and tips to avoid their blending in with the rest of the walk-through instructions or reference material. Take a look through a set of manuals and technical books and you'll see lots of examples of what works and what doesn't. Typically, adding some kind of border is of immense help, whether it means setting off a tip with a box around it or having a set of horizontal bars before and after a warning. Graphics can also be a nice touch, especially with warnings when you want to make it perfectly clear that this is something to watch out for, or not to ever do.
Wording
And then there's the issue of wording, which takes us back to the audience. When you're writing for a beginner or nontechnical audience, it's absolutely essential to question every assumption you might have about the readers' knowledge. Will they know this acronym? Just in case, include a spelled-out version in the text or in a glossary. Is there a simpler way to put this term? The vice president of marketing might have no idea what an API is, but if you use "a set of tools that lets programmers have their programs talk to our programs," it's wordier, but you get your point across.
For a technical audience, you can use more jargon (i.e., stacks, threads, and forks) without having to specifically spell out what you mean in layman's terms, but still don't go overboard. Define your acronyms if you can't be sure they're common knowledge. Don't use big words just to show off your vocabulary. Keep it simple and to the point; that's far more impressive than sending people for their dictionaries. In either case, technical or nontechnical, it can help to have people who fit your audience type read over the document and give you feedback.
Consistency
Finally, there's the issue of consistency. Decide up front if you're using metric or English units, or need to have both included for any measurement. Define the little things like whether you intend to use 5MB or 5 MB, 5 feet instead of 5', and so on. When you're referring to variables, this can get interesting: How do you want to refer to them when you're using a format such as variable = definition of value, as opposed to variable = example value? Perhaps name =
One important thing to be consistent with is how you're representing text that the user needs to type in. Some people use a monospace font such as Courier for user-entered text references. Others underline or bold. Be guided partially by the conventions in your industry and format, but in general, just do it the same way throughout the document(s). Keep a separate file open or piece of paper handy to record consistency issues and decisions as they come up.
Conclusion
Although it's often best to have a professional technical writer handling your documentation needs, sometimes developers are stuck having to write their own for a variety of reasons. Just take that same attention to precision and detail you use in your daily programming work and apply it to the text. Keep the formatting issues, language issues, audience issues, task issues, and so on, in mind and you'll find yourself with useable, readable documentation every time.