There are many preparatory steps in technical writing that you as a writer need to take before actually sitting down and start writing a technical document.

7 Issues to Consider

Here are 7 issues you need to consider in the pre-production phase of your documentation project:

Purpose

will you be generating the technical document in question? What is the exact reason? You’d better write this down before you do anything else. If you can’t write your purpose in one sentence, don’t start your project. This purpose is sometimes expressed in the Scope Document prepared by the project management.

Audience

You need to have a very clear idea of who the audience is and how they will use the document. This will determine the level of detail you’ll need to include in the document as well as the things that you can skip safely.

Deadlines

Next, you need to determine the time scope and all the important dates for the document. When are you supposed to deliver the first draft? The second draft? The final draft?

Outline

What will be the tentative chapters? Try to come up with a single sentence description of each chapter. What kind of components will the document have? TOC? Index? List of Figures? List of Tables? Glossary?

Files

If you are creating an online document like a help file, what kind of text, multi-media and support files will you need? Who will generate the “map ID” files? Where will you get them from? Who will provide them for you?

Contacts

Who will be your contacts, reviewers, Subject Matter Experts, and to whom will you report for the final approval on the document?

Documentation Plan

You would be much better off by compiling all this information into a Documentation Plan and have it approved by the Project Manager or the authorized representative of your customer before starting the project.
If you don’t do that, and in case anything goes wrong, be ready to be accused with having started the document project without clearly understanding the main purpose and audience of the document, the deadlines involved, and the specific content desired.

An approved Documentation Plan in hand will prevent all that and protect you when things go wrong.
Then comes the pre-production research phase. Most technical documents require considerable research before you sit down to write them.

Research involves many sources (Public domain image courtesy of Wikipedia)

7 Research Methods

Here are 7 research methods that you can use in your technical documentation project:

Existing Documentation

Insist on seeing every piece of paper ever produced on the project. This can be an old user manual, an installation handbook, engineering notes scribbled in a notebook, chat and discussion forum files, scope and spec documents, etc. You never know when you’ll discover a piece of information that would be vital for your document.

SMEs

Subject Matter Experts are great valuable resources for all technical writers. Do your homework well and draw up a clear list of important questions before contacting an SME since most are very busy people with not much time for unstructured “brain storming.”

Personal Experience

Personal experience through using the software or the product itself. Make sure you get your hands on the software or the product that you are documenting. There is no substitute to direct empirical data gathered from hands-on experimentation.

Personal Visits

Visiting the sites, customers, seeing the product in use. One excellent way to understand how a product or system operates is to visit the customer sites where the product is installed. That kind of visit can create the high-value trouble shooting guide and FAQ sheets that come in handy when things go wrong. That kind of knowledge is very hard to compile from the head office.

Conducting Web- and Tele-Conferences

With the technology available to us today it’s very easy to gather a group of SMEs, managers, users, and testers for a virtual conference where a technical writer can get answers to his or her questions.

Sending out Surveys

This rare method of information gathering can be a potent one if the right questions are asked and sent to the right parties.

Library and Internet Research

This is perhaps the most accessible information source. However, the dilemma for the technical writers is, if it’s on the Internet or in your public library, the chances are it’s “old stuff” and you don’t want to use it to document your brand new product or system anyways.
We technical writers are invited to document what has not been documented before. In that sense we always operate on the frontiers of human knowledge, making such easy searches not very fruitful and hopeful.

Takeaway

Start writing your document ONLY AFTER you’ve taken care of the 7 issues listed and used three or four of the 7 research methods outlined above. You won’t regret it.

RESOURCE

Key Concepts of Technical Writing to Create Great Documents