Flow of Content in Help Documentation


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

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • The following factor for content depends on TOC Structure of Document:CompleteFindable
  • The following factor for content depends on elements used in the Document:ConsistentUnderstandable
  • Accuracy depends on you and it can be improved by validating the content before the release.
  • 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