Flow of Content in Help Documentation

Content Quality• Flow of Content in Guides (Targeting Various Audience)

• General Guidelines• Installation Guide• User Guide• Configuration Guide• Administrative or Service Guide

• Using Various Document Elements • Bulleted List• Numbered List• Flow Diagram• Table• Others

Agenda:

Flow of Content in Guides

Accurate

Complete

Consistent

Understandable

Findable

Content Quality – Impact of Document Structure

• Ensure you have done enough audience analysis• Explore other guides for structure and organization of

content• Ensure the topics/sections are modular• Use more screen shots according to the audience

requirements• Make the TOC flow logical and audience must have the feel

to come back• Publish your content on a regular basis to see how it looks

for the audience• Validate the new content before the release [Optional]

Flow of Content in Guides – General Guidelines

INSERT COPYRIGHT INFO HERE

Information Architecture

Introduction System Requirements

◦ Hardware Requirements◦ Software Requirements

Pre-requisites Installation Flow Diagram[Optional] Procedure to Install Post-install Configuration [Optional] Procedure to Uninstall [Optional] Use of Caution, Note, and Warning× Very detailed explanation of Windows-related

configuration, so point to Windows Documentation for detailed reference

Flow of Content in Guides – Install Guide

Flow of Content in Guides

Introduction <Task 1> <Task 2> …… <Task n> Workflow takes the priority and mostly

used task takes the next priority× Too much levels in TOC (Table of Contents)

Flow of Content in Guides – User Guide

Introduction System Requirements [Optional] Pre-requisites Flow diagram [Optional] <Configuration 1> <Configuration 2> …… <Configuration n> Use Caution, Note, and Warning× Duplicate content from Installation Guide, so provide

cross-references

Flow of Content in Guides– Configuration or Service Guide

Introduction System Requirements Architecture Diagram [Optional] <Task 1> [e.g., Add User or Group] <Task 2> [e.g., Back up or Restore] …… <Task n> Use of Caution, Note, and Warning× It is obvious, so will not explain

Flow of Content in Guides– Administrative or Maintenance Guide

Accurate

Complete

Consistent

Understandable

Findable

Content Quality – Impact of Document Elements

Using Various Document Elements

• Non-sequential• Use it to simplify big paragraphs• Used as sub-steps in our Guide× Avoid using with Note or inside table× Don’t list the field names with definitions or

actions. Use Table in this case

Using Various Document Elements– Bulleted List

• Use with “Procedure Intro” paragraph tag• Do not exceed 10 steps in a topic and limit to 20

steps in special cases• Use sub-steps with bullet• If the sub-steps can standalone as a procedure,

make it a separate topic/section Provide step result for all steps to make the

procedure interactive× Overdo nested list or use the “List Number 2”

paragraph tag

Using Various Document Elements– Numbered List

• Explain the workflow with flow diagram• Use different colors for boxes (process) to

differentiate modules• Ensure the diagram fits in the page or split

them Check with Others or Laraine if you are not

sure with the choice of flow diagram×Don’t use Fluorescent colors (straining the

eyes) and small font size

Using Various Document Elements– Flow Diagram

• Use for long list of fields to be described with definitions or input instructions

• Comparison of the applications, availability of features, etc.

Embed the table if you are using in several topics×Avoid Numbered list inside table or bulleted

list for easy of reading

Using Various Document Elements– Table

• Use Hyperlinks wherever possible• Point to Third-party application help

Example: Microsoft Windows Help• Consistent use of terms and definitions

through out the document

Using Various Document Elements– Others

• Use more white space: Bulleted List and Indented Bullet Lists More paragraphs, it is better Others are taken care by Page Layout

(Template) Diagrams

oFlow diagrams oArchitecture diagrams oOther illustrations

Using Various Document Elements– Others [Contd.]

Know the use of:◦ Warning: To warn readers about the possibility of minor injury

or data. ◦ Caution: To warn readers about possible damage to

equipment or data or about potential problems in the outcome of what they are doing. 

◦ Note: To emphasize points or remind readers of something, or to indicate minor problems in the outcome of what they are doing. Also, other useful information to assure that you get the most from your application.

Using Various Document Elements– Others [Contd.]

Accurate

Complete

Consistent

Understandable

Findable

Content Quality – Impact of Document Structure

Needless to mention that…….

Definition of Note, Warning, Caution from: http://www.prismnet.com/~hcexres/textbook/notices.html

Images◦ Information Architecture - http://www.sitepoint.com

◦ You are real information architects - http://oxfordtechnologyventures.com

Content Quality- www.acrolinx.com

Credits