Documentation Insight

Documents can be classified into:

Marketing Document : Brochures, Case Study, Press release, Product handbook, Marketing Script, White Paper, Advertising Copy, Data Sheet.

Reporting Document :  Magazine, News Articles, Technical Paper, Annual Report, and Website.

Instructing Document:  User Guides, Manuals, Installation Materials, Training Guide, Online Tutorial, Quick Start Guides, Job Aid and Glossary.

Plan and prepare your documentation because “Failing to Prepare is preparing to Fail”.

Understand the requirements:

·         Study, research and understand the functional domain.

·         Know your audience (internal /external customer).

·         Study the Document specification from client and company.

·         Develop client specific documents.

Outline the Document:

·         Have an overview of the project.

·         Take notes.

·         Closely work with SME’s / Points of Contacts and be reminded of the information to be collected.

·         Have an understanding of the application / product over frame of reference.

·         Relate the information gathered and identify the gaps.

·         Try to break down complicated task / process and sequence them.

Plan the Structure:

·         What is the primary content?

·         What is the main presentation idea?

·         What methods of searching, viewing, and browsing the content will be used?

·         What are the convincing features?

Thought about the content?

·         Is the content updated?

·         Do the Application / Product use the existing content?

·         If new, how it is captured and created?

Writing Styles:

·         Remember the user in mind before writing the content.

·         Write the content in a clear and simple language.

·         Use jargons accordingly.

·         Use active voice and address the user directly.

·         Avoid ambiguous and long sentences.

·         Use Gender -Neutral language.

·         Manage Localization issues (Few contents are translated not directly but done by language translators).

Book Design Components

·         Cover Page

·         Copyright notice

·         Contact and Support Information

·         Table of Contents

·         Cross References

·         Table of illustrations and tables

·         Preface / About the Guide

·         Chapters / Topics (Online Help)

·         Hypertexts

·         Glossary

·         Appendixes

·         Trouble Shooting (Manual Guides)

·         Index

Document Prototyping

·         Develop a Template (Print / Online)

·         Develop a Style Guide

·         Work with the SME’s to develop contents of a sample section from mockup’s

·         Learn to write sample section for a perspective user

·         Write descriptive topics and contents relevant to the topics

·         Learn to work on authoring (FrameMaker, Word), help (RoboHelp, WinHelp) and screen capturing tools (SnagIT, Photoshop, GIMP).

·         Save your time by having hands on experience in single sourcing tools like FrameMaker, Mif2Go, DITA Conversion and Web Works Publisher.

Other Considerations

·         Technical Requirements

·         Delivery Requirements

·         Documentation guidelines

·         Staffing

·         Timeline

·         Prototyping

·         Style Guide

·         Template (Online/Print)

·         Template Changes

·         Changes to the product features or upgrades

·         Bugs

·         changes to document structure

·         Look for standardization and consistence across documents

·         Develop the initial document in draft status

·         Do a self review

·         Conduct Peer Review (Format, Font and grammar, Handling Personality Clashes)

·         Do a Quality Review( Factual Errors, Modification, Completeness)

·         Send your documents for a functional and technical review

·         Develop checklist on all the reviews and Incorporate track changes

·         Incorporate Peer, functional and technical reviews.