Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

•

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

•

General Guidelines
Installation ...
Flow of Content in
Guides
Accurate
Complete
Consistent
Understandable

Findable
•
•

•
•

•

•

•

Ensure you have done enough audience analysis
Explore other guides for structure and organization of co...
Information Architecture

INSERT COPYRIGHT INFO HERE



Introduction
System Requirements

◦ Hardware Requirements
◦ Software Requirements

Pre-requisites
 Installation Flow...
Flow of Content in
Guides







×

Introduction
<Task 1>
<Task 2>
……
<Task n>
Workflow takes the priority and mostly
used task takes the next...
Introduction
 System Requirements [Optional]
 Pre-requisites
 Flow diagram [Optional]
 <Configuration 1>
 <Configurat...
Introduction
 System Requirements
 Architecture Diagram [Optional]
 <Task 1> [e.g., Add User or Group]
 <Task 2> [e.g....
Accurate
Complete
Consistent
Understandable

Findable
Using Various
Document
Elements
•
•
•

×
×

Non-sequential
Use it to simplify big paragraphs
Used as sub-steps in our Guide
Avoid using with Note or insid...
Use with “Procedure Intro” paragraph tag
• Do not exceed 10 steps in a topic and limit to 20
steps in special cases
• Use ...
Explain the workflow with flow diagram
• Use different colors for boxes (process) to
differentiate modules
• Ensure the di...
Use for long list of fields to be described with
definitions or input instructions
• Comparison of the applications, avail...
•
•

Use Hyperlinks wherever possible
Point to Third-party application help
 Example: Microsoft Windows Help

•

Consiste...
•

Use more white space:
 Bulleted List and Indented Bullet Lists
 More paragraphs, it is better
 Others are taken care...


Know the use of:
◦ Warning: To warn readers about the possibility of minor injury
or data.
◦ Caution: To warn readers a...
Accurate
Complete
Consistent
Understandable

Findable
Needless to
mention
that…….


Definition of Note, Warning, Caution from:

http://www.prismnet.com/~hcexres/textbook/notices.html


Images
◦ Informat...
Flow of Content in Help Documentation
Upcoming SlideShare
Loading in …5
×

Flow of Content in Help Documentation

467 views

Published on

Desgining TOC is important step in technical writing process. The TOC varies according to various guides and audience.

Published in: Technology, Business
  • Be the first to comment

  • Be the first to like this

Flow of Content in Help Documentation

  1. 1.  • Content Quality Flow of Content in Guides (Targeting Various Audience) • • • • • • General Guidelines Installation Guide User Guide Configuration Guide Administrative or Service Guide • • • • • Bulleted List Numbered List Flow Diagram Table Others Using Various Document Elements
  2. 2. Flow of Content in Guides
  3. 3. Accurate Complete Consistent Understandable Findable
  4. 4. • • • • • • • 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]
  5. 5. Information Architecture INSERT COPYRIGHT INFO HERE
  6. 6.   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 
  7. 7. Flow of Content in Guides
  8. 8.       × 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)
  9. 9. 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 
  10. 10. 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 
  11. 11. Accurate Complete Consistent Understandable Findable
  12. 12. Using Various Document Elements
  13. 13. • • • × × 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
  14. 14. 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 •
  15. 15. 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 •
  16. 16. 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 •
  17. 17. • • Use Hyperlinks wherever possible Point to Third-party application help  Example: Microsoft Windows Help • Consistent use of terms and definitions through out the document
  18. 18. • Use more white space:  Bulleted List and Indented Bullet Lists  More paragraphs, it is better  Others are taken care by Page Layout (Template)  Diagrams o Flow diagrams o Architecture diagrams o Other illustrations
  19. 19.  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.
  20. 20. Accurate Complete Consistent Understandable Findable
  21. 21. Needless to mention that…….
  22. 22.  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

×