Tips for Writing Technical Documentation

By | 2011/09/04

Technical writers often work with software developers or system administrators to document procedures, provide instructional documentation, or perhaps other end user guides or information. Here are some tips!


Good documentation has these qualities:

  • Easy to read
  • Assists user to overcome or solve problems and perform tasks more efficiently
  • Easily accessible
  • Targeted to its audience
  • Aesthetically attractive
  • Technically and grammatically sound

Are you writing API documentation for developers? Or how-to guides for end users? Is your documentation a wall of text or does it have clearly defined sections, examples, and screenshots? Is the documentation difficult to find, or dependent on a particular browser or plugin?


We have all seen the random man page which is perhaps not that helpful:

ASDF(1)                     Linux User's Manual                     ASDF(1)

NAME
       asdf - runs qwerty asdf qwerty

SYNOPSIS
       asdf - [ options ...]

DESCRIPTION
       asdf is useful for qwerty asdf actions.
 
OPTIONS
	-a, do not use, obsoleted by -e
	
	-C, will reflect different from -f

	-e, combines options of -x unless -g is specified


(And of course no examples at the end!)


Other examples are instructional guides that are created in a format which does not match or suit the target audience.

For online web-based software, online HTML manuals make sense along with providing an optional PDF download as well!

PDF-only or even worse .DOC only documentation for an online product does not match the target user environment or experience.

In the case of online HTML documentation, the HTML markup should not be dependent on any plugin or browser and render properly in any modern browser.

Good luck with your writing!

Leave a Reply

Your email address will not be published. Required fields are marked *

Notify me of followup comments via e-mail. You can also subscribe without commenting.