Latest posts by techwriter (see all)
- Test Your Knowledge of 4 Basic Fonts – Drag & Drop - January 27, 2017
- How NOT to Design a Web Site - January 25, 2017
- Hazards of Poorly Written Technical Documentation - December 26, 2016
© 2010 Ugur Akinci
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.
Here are 7 issues you need to consider in the pre-production phase of your documentation project:
1) PURPOSE. Why 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.
2) 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.
3) 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?
4) 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?
5) 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?
6) CONTACTS. Who will be your contacts, reviewers, Subject Matter Experts, and to whom will you report for the final approval on the document?
7) 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)
Here are 7 research methods that you can use in your technical documentation project:
1) 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.
2) 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.”
3) 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.
4) 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.
5) 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.
6) 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.
7) 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.
IN SUM: 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.