The Science of Technical Documentation Strategy

Documentation strategist  is a new nomenclature for a class of technical authors who determine the plans and goals of documentation for a particular company. I did a search of the word in a couple of search engines, but I did not hit upon anything relevant. However, this does not mean that companies are not using documentation strategies.

In most companies, documentation strategies are evolved as inputs from both technical writers and their direct or indirect managers. For example, the decision not to revise a certain document to capture a new product defect is taken as a result of documentation strategy.

Why do we need documentation strategy?

Technical documentation is no longer seen as an afterthought of a product release. Good technical documentation has proved to not only reduce the volume of calls to contact centers, but also assist product support specialists  in resolving customer conflicts.

Here is a good article that further explains the repercussions of cost cutting in the technical documentation field: http://www.technicalcommunicationcenter.com/2010/09/30/the-hidden-high-cost-of-cutting-down-on-documentation/

 [When I was a technical resolution expert for a major computer company, I used to go to the Microsoft knowledge bases to find answers to any Windows related queries. Not only was I able to resolve my customer’s issue, but by forwarding the particular article to the customer, I ensured that he/she will not be calling again for the same issue.]

As the number of products from a particular company increase, so does the amount of documentation required to support the products. With the increase in the amount of documentation, the complexity increases.

There is a requirement to maintain consistent style and quality across all documentation of a particular company. Also, as a part of documentation strategy, one needs to look into minimalism and cost cutting.

Consider the following questions for the documentation requirements of XYZ product:

• How many document types does XYZ product need?
• How often will each document need to be revised?
• Are any or all of the documents required to be printed?
• How will the documents be delivered to the customer: online HTML, online PDF, documentation CD, etc?
• What authoring and production tools will be used in developing the documents?
• How are the documents going to be stored?
• What will be the documentation life cycle?
• Will the documents need localization?

The answers to all the above questions are decided by a documentation strategist. In essence, the decisions are taken based on cost and customer experience. A documentation strategist has liaisons with the engineering group, the legal department, the marketing group and the product support group to evolve decisions for a stable, cost saving and customer friendly documentation strategy.

Who makes a good documentation strategist?

Not just any technical writer be a documentation strategist. However, a documentation strategist must have a background in technical writing.

• Are you able to quickly analyze documentation requirements for products?
• Do you consistently think of how to make documentation processes more effective?
• Are you buried head-deep inside the products of your company or do you often do comparisons and explorations in documentation of other companies?
• Can you take decisions that can affect the whole documentation department of your company and base them upon sound logic and research?
• Are you a good communicator and not afraid to ask questions to people who might be higher up than you in the corporate ladder?
• Can you justify your decisions to the company big wigs and evolve a documentation strategy to ease not only your department but your customers?

If you answer yes to all of these questions, you are definitely on your way to becoming a document strategist. Congratulations!

The Science of Lists in Technical Communication

Lists play an important role in technical writing. Lists, whether unordered (bulleted) or ordered (numbered) are a visual treat to your reader. When a list is set within rows of paragraphs in a document, the reader’s attention is immediately riveted to it.

Of course, not everything and anything can be put in a list. You should create a list only out of a set of similar nouns, phrases or sentences.

Note: An ordered list is used when the sequence of the list is important. If two components of an ordered list interchange position, the meaning is disrupted.

Note: Use an in-sentence list for unordered components not more than five.

For Example

Bring the following to the meeting: paper, pen and your laptop. 

An Unordered List

In technical communication, an unordered list is offset by bullets. Your word processor will have different styles of bullets. You should choose the type of bullet for your template based on the type of your audience.

For Example

An advertising pamphlet for dog owners, which advertises a particular type of food for their pets, may have bullets styled as doggy prints. On the other hand, a Repair Manual for an air conditioner for service engineers may use a more formal bullet style like a dot.

Whatever be the type of list that you author, there are some universal guidelines that you should refer to:

•  All lists must be preceded by a lead-in sentence that introduces the list.
• The lead-in sentence must be separated from the bulleted or numbered set by a colon.
• Do not use “a”, “an” or “the” in front of the list components, unless the numerical quantity is required to complete the meaning.
• Start each list component with a capital letter.
• Do not put a period after each list component, unless each list component is a sentence in itself, like the current list you are reading.
• Maintain parallelism in the sentence structure of your list components.
• The lead-in sentence must carry meaning while standing on its own.

Formatting Styles for Unordered Lists

Do follow the guidelines below for formatting unordered lists:

• The bullet style must be indented from the paragraph style by at least a tab.
• The spacing between the bullet and the first letter of the component must be at least a single space.
• The entire bulleted list must be separated from the preceding and succeeding paragraphs by at least a single line.

For Example

Ensure that you have the following utensils before baking the cake:

• Baking tray
• Spatula
• Large bowl

Sub Lists

Sometimes a particular list component might have an additional sub list. In this case, follow the guidelines below:

• The Level 2 bullet must be preferably visually different from the Level 1 bullet. (Alas, my style sheet does not allow it yet.)
• The Level 2 bullet must be indented by at least a tab from the Level 1 bullet.

For Example

Connect the following components to the computer:

• Power cable
• Display cable
• Keyboard
• Mouse
• Any other peripheral like:  
  • Printer
  • Modem
  • Camera

An Ordered List

I have already mentioned that an ordered list is when the sequence of components in important for the meaning of the list.  You can follow the guidelines below while making an ordered list:

• Use numbers or alphabets to indicate an ordered list.
• If you have a sub list within the ordered list, use a different set of number or alphabet styles. For example, you can use numbers for Level 1 and alphabets for Level 2.
• Use a lead-in sentence that is complete in its meaning by itself.
• Maintain parallelism.
• Use a period or a pair of parenthesis to separate the numbers/alphabets from the actual list components. If you are using parentheses, do remember to close them.
• Do not use periods in the components of a numbered list, unless each component is a sentence in itself.
• The formatting rules for ordered lists are similar to that of unordered lists.

Exercise

What is incorrect in the following list styles?

Remember to bring the following items for your hiking trip: water bottle, mosquito repellant, sleeping bag, matches, tinned food, extra set of clothes, medicine box, map, compass, hiking boots, and a tent.

Answer: There are too many items in the list. For clarity, it is best to use a vertical list as opposed to an in-sentence list if the number of items exceeds five.

XYZ hard drives provide the following benefits:

• SMART-compliant
• Hot-swappable
• Hardened chassis to prevent wear and tear.

Answer: Parallelism is missing.

Add the following ingredients to the soup in order. Fry each ingredient for five minutes before adding the next:

1. Garlic
2. Ginger
3. Onions
4. Carrots

Answer: The lead-in sentence is succeeded by another sentence. In this case, a colon is not required. Use a period.