The document provides guidelines for creating technical documentation with good information architecture and flow. It recommends analyzing the intended audience and exploring other guides for structure. The document outlines common sections for different types of guides such as introductions, requirements, installations, configurations, and tasks. It provides tips for using headings, lists, diagrams, tables and other elements to improve readability, understandability and findability of content. Cautions are given about nested lists and color usage. Proper use of notes, warnings and cautions is also discussed.

2. 
•
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

3. Flow of Content in
Guides

4. Accurate
Complete
Consistent
Understandable
Findable

5. •
•
•
•
•
•
•
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]

6. Information Architecture
INSERT COPYRIGHT INFO HERE

7. 

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


8. Flow of Content in
Guides

9. 





×
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)

10. 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


11. 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


12. Accurate
Complete
Consistent
Understandable
Findable

13. Using Various
Document
Elements

14. •
•
•
×
×
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

15. 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
•

16. 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
•

17. 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
•

18. •
•
Use Hyperlinks wherever possible
Point to Third-party application help
 Example: Microsoft Windows Help
•
Consistent use of terms and definitions
through out the document

19. •
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

20. 
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.

21. Accurate
Complete
Consistent
Understandable
Findable

22. Needless to
mention
that…….

23. 
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