How to Write Goal-Focused and Structured Technical Documents

PREMISE

• Most of the technical documentation that exists in the world today is feature-focused.
• It is also unstructured: there is no well-defined hierarchy between the components of the document. For example, there is no enforcement of a hierarchical rule like “every task description shall be followed by a reference section.” See this related article.

PROBLEM

Most of the time the end-user has a problem to solve, not a desire to read every feature of an option. Most of the current documents do not address that end-user need since the content creators do not write them with a goal-focused framework.

FEATURE-FOCUSED TECHNICAL DOCUMENT STRUCTURE

SOLUTION

1. Start from GOALS, that is, what the users are trying to achieve or keeping them awake at night.
2. Determine the ACTIVITY that will make reaching that goal possible.
3. Provide the essential INFORMATION that will make that activity possible.

EXAMPLE

1. GOAL: To allow contractors into a site only during certain hours of the day.
2. ACTIVITY: Create a CONTRACTOR user type with limited access code.
3. INFORMATION: Steps to follow to create a “Contractor” user type with limited access code.

GOAL-FOCUSED TECHNICAL DOCUMENT STRUCTURE

3-TOPIC FRAMEWORK

This goal-oriented structure requires that you write documents according to a 3-topic document framework currently used by some Fortune 100 corporations like Rockwell International.

• DITA: These are the standard structured-authoring topic categories used by DITA (Darwin Information Typing Architecture) scheme. Thus, re-writing our documents by “bursting” the current feature-laden catch-all topics into smaller and leaner more-granular topics would provide a smooth transition to XML-based structured authoring as well.

1. First topic: CONCEPT. Answers the “What is?” question. Derives from the customer GOAL or PAIN POINT.
2. Second topic: TASK. Answers the “How do I do it?” question. Derives from the ACTIVITIES INFO needed to achieve that goal.
3. Third topic: REFERENCE. Answers questions like “What are the specs?” or “What is the list of all the commands available?” Derives from the FEATURES DATA to support the activities in question.

BENEFITS

1. CONSISTENCY. Structured authoring software (like Structured FrameMaker) enforce the topic rules built into a structured document. This builds user confidence in the documents and creates a more positive user experience.
2. MINIMALISM. The document created has a minimum number of topics. Each topic addresses only one finely-tuned issue. Users enjoy minimum fatigue and cognitive overload. They have much better comprehension and information retention.
3. REUSABILITY. Since topics are granular and modular, you can reuse them in combination with other topics. For example, you can use a topic that describes how to configure access codes by creating a contractor user type. This lowers your cost of authoring.
4. LOWER COST OF LOCALIZATION. Studies show that this type of documentation minimizes the costs of localization.
5. SINGLE SOURCING. Once created, you can deliver this type of XML-based documents on a number of different platforms by using the same source files, including HTML5 responsive-layout deliverables for mobile platforms, Kindle and ePub formats, MS HTML Help, Web Help, and like.
6. ECONOMY OF UPDATES. To update such documents it is not necessary that you update each deliverable individually. Once you update the XML-based source files, you can republish and push them on to different delivery platforms. This lowers your cost of production and distribution.

WHAT IS NEEDED?

1. Goal-oriented structured documentation require management by-in. Without management support, you cannot accomplish the shift from unstructured to structured authoring.
2. The writers need to have access to “customer pain-point” data. Without such data the writers would not know what the important documentation GOALS are.
3. The writers and the management need to have consensus on the “framework,” that is, the kind of TOPICS that will be included in the documents.
4. Additional tech writing hours may be needed to sift through both the customer goals and break down topics to individual CONCEPTS and then rebuild them again into a structured document. The initial phase might be very labor-intensive indeed. But once it is done, future updates should be easy and less labor-intensive.