Developing Good Documentation

Author: Larry Sherrod

Planning

• First, Know your Subject

• Think of Your Audience

• Develop your Subject

• Divide Your Subject into a Table of Contents

• Determine the Form of Your Published Output

• Know Your Tools

Audience

• What level of knowledge should they hope to achieve

• What is their current level of knowledge

• How easily should they be able to navigate your content

• How will they use your content and what published form should it be

Subject and Contents

• Don’t make your subject too broad

• Don’t try to cover too many details

• Be very specific about the expectations of your user

Published Output

• Determine where your output will reside

• Determine how your users will access the output

• Determine how often they need to access your output during execution of their process

Tools

• Text Processing

• Image Editing

• Video and Audio Editing

• Interactive Products

Tools – Text Editing

• Microsoft Word– This is the most common business package. It has plenty of editing capability

and can easily include images and screenshots of your applications.

• Open Office– While this package has been around for many years, it hasn’t be in common use

in business because of the dominance of Microsoft. It is gaining in the user community because it is an open source application and is free to use. It has all the same features as Microsoft and users of either product can read each others output.

• Notepad– I am not trying to be funny here. Don’t discount this simple and easy to use

package. If all you need is simple text instructions, it is fine. Many users find all the documentation they need is some simple printed text they can post near their work station.

Tools - Image Editing

• Microsoft Paint– This is easy to use and quick to learn. It’s on almost every PC in use.

You can paste screenshots right into it and use the tools to annotate and caption the image. Try to stay away from saving as .bmp files, stick to JPEG files.

• Snag It– This is my personal favorite and the application I use. It is inexpensive,

easy to use and has lots of great features for enhancing your images. It can even capture video from your PC as well.

• Others– There are far too many image packages out there for me to critique. If

you have a favorite and are comfortable using it, then stick with it.

Tools – Video and Audio Editing

• CamStudio– This is a free open source product. It is low in features but it does the

basics. If you don’t have a big budget but still want to provide visual and audible content, it works fine.

• Camtasia– This is a product from the same guys that make Snag It. It is a bit pricy

but it is very full featured. If you want to make professional looking content and are will to take the time to learn the product, it is a good application.

• Others– There are tons of other products out there but the ones above were

developed for capturing video from the PC. You just don’t need a product you use for editing vacation videos. That said, if you like what you already have, use it.

Tools – Interactive ProductsNote: As far as I know, none of the interactive or “e-learning” products are inexpensive. These

products are full featured and the learning curve for them can be long. They are designed as enterprise solutions for medium to large corporations. Be prepared to make an investment in time and money.

• Adobe Captivate and Authorware– This is a great package for developing engaging learning solutions. It is

harder to learn than UPK but it has been around longer and will work with any application running on a PC. It is far less expensive than UPK but it wasn’t design as a server application to support multiple authors.

• Oracle UPK (user productivity kit)– It is by far the best package for developing content for application users

of Oracle, JDE, Peoplesoft. It is why is was designed. It can function as a server application for multiple authors or as a stand alone developer. It is very expensive compared to other products but it is very feature rich.

• Others– There aren’t many other applications that provide these features. If you

find any, let me know.

Conclusion