How to Write Technical Documentation
Things You'll Need
- Authoring tool
- Subject matter expert
Technical communication or documentation is the process of conveying "user-friendly" information through writing about a particular topic to an intended audience. Technical documentation ranges from a business email to business reports to a user guide or help system. Many only turn to documentation “when all else fails.” No wonder documentation is often shoddy at best; nonexistent at worse. Computer companies may feel that their software is so easy, they don’t need documentation. But technical documentation is less expensive than technical support calls. Before you can develop good technical documentation, you need to know that effective technical documentation is a well-planned and executed mission.
Determine purpose and audience. You need to know why you are creating this documentation and who will be reading it. The type of documentation you create will be different if your audience is a car mechanic than if your audience is a software engineer.
Gather information. The person creating the documentation is often a writer and not the subject matter expert. It is important to gather the information so that you can document it. Collecting the information can mean doing research, interviewing a subject matter expert, or experimenting with the product itself, as in the case of a software program.
Organize and outline information. You may start with an existing document or a template. It’s important to enter what information you have and leave the areas blank where you need to gather more information. This will be your working document, and you will build on it. Jotting down what you do have even if you have large areas of empty space will boost your confidence that you are moving forward in the project.
Write the first draft. This is when you start filling in the blanks and allowing for a flow of ideas to stream from your consciousness. Do not stop that flow by revising at this stage.
Revise and edit. You may want to put the document away for a period of time so that you can give it a fresh look. Then focus on topics that need more attention; shorten, expand or delete sections; or rearrange paragraphs, sentences, or entire topics. You will also want to edit for style, grammar and context.
An editing checklist is handy so that you can edit for different points during separate passes.
Develop good team-player skills and an understanding of how each subject matter expert prefers to work to keep this relationship from becoming adversarial.
- An editing checklist is handy so that you can edit for different points during separate passes.
- Develop good team-player skills and an understanding of how each subject matter expert prefers to work to keep this relationship from becoming adversarial.
From the early days of electronic publishing, Kathy Holmes has worked for major printers and publishers such as McGraw-Hill and Ziff-Davis in the San Francisco Bay Area. From there she segued into technical writing/editing in Silicon Valley, followed by writing fiction and nonfiction, blogging, and writing online content.