Latest posts by techwriter (see all)
- What is the Readability Index of Your Writing? - November 20, 2017
- Should Technical Writing be Boring? And if Yes, Why? - November 15, 2017
- How to Create a Custom-Designed Header in MS Word that Would be Available to All Other Word Documents - November 13, 2017
© Ugur Akinci
- 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.”
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 they are not written with a goal-focused framework.
FEATURE-FOCUSED TECHNICAL DOCUMENT STRUCTURE
- Start from GOALS, that is, what the users are trying to achieve or keeping them awake at night.
- Determine the ACTIVITY that will make reaching that goal possible.
- Provide the essential INFORMATION that will make that activity possible.
- GOAL: To allow contractors into a site only during certain hours of the day.
- ACTIVITY: Create a CONTRACTOR user type with limited access code.
- INFORMATION: Steps to follow to create a “Contractor” user type with limited access code.
GOAL-FOCUSED TECHNICAL DOCUMENT STRUCTURE
This goal-oriented structure requires documents be written 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.
- First topic: CONCEPT. Answers the “What is?” question. Derives from the customer GOAL or PAIN POINT.
- Second topic: TASK. Answers the “How do I do it?” question. Derives from the ACTIVITIES INFO needed to achieve that goal.
- 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.
- CONSISTENCY. The topic rules built into a structured document are enforced by the structured authoring software (like Structured FrameMaker). This builds user confidence in the documents and creates a more positive user experience.
- MINIMALISM. Topics are kept to a minimum. Each topic addresses only one finely-tuned issue. User fatigue and cognitive overload are kept to a minimum. Comprehension and retention are maximized.
- REUSABILITY. Since topics are granular and modular, they can be reused in combination with other topics. For example, a topic that describes how to configure access codes can be used with creating a contractor user type. This lowers cost of authoring.
- LOWER COST OF LOCALIZATION. This type of documentation has proven to minimize the costs of localization.
- SINGLE SOURCING. Once created, this type of XML-based documents can be delivered 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.
- ECONOMY OF UPDATES. To update such documents it is not necessary to update each deliverable individually. Once the XML-based source files are updated, they can be republished and pushed on to different delivery platforms. This lowers cost of production and distribution.
WHAT IS NEEDED?
- Goal-oriented structured documentation require management by-in. Without management support, the shift from unstructured to structured authoring cannot be accomplished.
- 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.
- 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.
- 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.