The process description in technical writing and how to make it work

“Process description” is describing a process, i.e., a sequence of events. The process is the set of instructions in manuals that you provide to the reader (end user) in order for them to achieve an end result. The end result could be how to install, repair, or assemble something. The end result may not be a tangible, hand-held product, but may be training or reference material. In describing a process, you provide instruction and information.

This is the core purpose of most technical manuals.

Another word for process description is procedure. In your English writing class, this was probably referred to as expository writing. Expository writing attempts to explain, illuminate or “expose” something. (Expository: 1620s, from Medieval Latin expositorius [1].)

What’s necessary to describe that process?

Actually, writing the sequential steps isn’t too difficult, but it’s the preparation leading up that part of the process that entails most of the work. The following is what technical writers should consider important to facilitate the process description.

What’s the purpose of writing your manual?

First of all, what are you trying to accomplish in writing your manual? What’s the purpose? That should be easy enough to answer since an assignment is given to you by your supervisor or the person that’s paying you. “We need to explain how to install or upgrade our new line of widgets” (for example). Or, it may be a diagnostic manual for field technicians, or for subcontractors using your company’s product.
Your supervisor just gave you the purpose. You’ll have support from fellow coworkers on how that product works. All you have to do is get that information together and present it.

If you’re a private contractor, you’ll have to decide whether you have the expertise to handle a given assignment. You’ll need to gather enough information to make the manual factual, organized, and complete.

Assessing your target audience.

successful-targetThis is a common question tech writers must take into consideration. It’s important. How will you present your material? For a manual written to field technicians within your company, you’ll freely use the company’s lingo. To the public/consumer, you’ll need to avoid (your) company specific jargon.

You’ll also have to consider what you can and can not include in your manual. Field technicians and costumer support may need extra, proprietary information that’s exclusively used “in-house,” while that same information would be detrimental if released to the public.

Make an outline.

outlineThis may sound like more of a hassle than it’s worth. But for longer, complex manuals, it does help. Think of it as a blueprint that builders use before they start construction. Although it’s easy enough to change text around with today’s word processors, a general plan helps to further shape your manual as you plan it out on paper.

Personally, once I have an outline, I usually create a table of contents with it. Then I start filling in the gaps. Most of the time it works, sometimes it doesn’t. It’s simply an option, a time saver, to use your outline to construct your TOC.

Make it easy to read and understand.

Keeping the following thoughts in mind beforehand helps to avoid rewriting your material after the fact.

  • As mentioned before, keep the material readable. Technical jargon directed at the average reader should be avoided. If you need to use technical words, keep it to a minimum and explain what the word means. A glossary is an option too. Replace difficult words with simple words when possible.
  • Keep your sentences at a reasonable length. Short sentences are all right, but the text appears choppy if you have too many and your thoughts will appear as disconnected as your text. Sentences too long tend to seem vague, which leads to confusion.
  • mapProvide an introduction to the manual. It helps the reader understand the content better by providing an overview. The introduction tells the reader what to expect, which is kind of like reading a road map before the trip.An introduction often states who the manual is for, how it is expected to be used, and offers basic instructional text. If the introduction becomes too lengthy, consider a “purpose and scope” section.
  • Include an “Organization of this Manual” page or section (same as “About this Manual”), especially when the manual is lengthy and complicated. An organization page/section helps readers in two ways: 1) It gives them a framework of the manual and partitions the product into easier to understand components, and 2) It helps readers to understand the text by fulfilling their expectations: “What’s in here and what am I looking at?”
  • Clearly defined sections or divisions (and subdivisions) are necessary. Use of style sheets helps to keep headings consistent looking and facilitates with creating a table of contents. If your software allows it, add an index too.

Explain only what needs to be said.

It’s easy to get carried away with explaining too much. Paragraph sprawl occurs when unrelated or irrelevant topics are introduced. The writer starts to lose focus of what needs to said.

If you feel the need to explain how something works before the section on the process/instructions, try to keep it brief. Background knowledge on a product often helps the reader to understand the product better, but it’s the process/instructions that’s the purpose of your writing.

Writing the process or instructions is now a piece of cake.

steps_smallYou’ve done all the preliminary work; now explain step by step what needs to be done: Step A, Step B, Step C….

If you need directions, you’ll get together with those in engineering or assembly for your process description. If possible, have the product on your desk so that you can use it as a model as you sequentially write the process of assembly, diagnosis, or software configuration.

To make the process complete, proof your work.

Writing is a recursive process. Expect to re-edit your work at least several times; more, time permitting.

proofread

Notes:

[1] http://www.etymonline.com/index.php?allowed_in_frame=0&search=Expository

Leave a Comment