Developing Good Documentation

100 %
0 %
Information about Developing Good Documentation
Technology

Published on October 31, 2008

Author: larrysherrod

Source: slideshare.net

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

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

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

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

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

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.

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.

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.

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 Products Note: 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 .

Note: 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

Add a comment

Related presentations

Related pages

10 Things You Can Do to Create Better Documentation

10 things you can do to create better documentation. ... "Documentation is a vital part of developing and ... creating good documentation is good ...
Read more

Five Principles to Good Documentation Writing (Good ...

Five Principles to Good Documentation Writing (Good Documentation Series) ... May 31, 2013. 0 comments Developing Documentation. development programming .
Read more

ARCHIVED WEBINAR :: Principles of Good Documentation

Archived Webinar :: Principles of Good Documentation. ... Roles and responsibilities of Quality Personnel in developing and implementing good documentation ...
Read more

GOOD DOCUMENTATION AND QUALITY MANAGEMENT PRINCIPLES - WHO

GOOD DOCUMENTATION AND QUALITY MANAGEMENT PRINCIPLES Vimal Sachdeva Technical Officer (Inspector), WHO Prequalification of Medicines Programme
Read more

Chapter 4 Final 0910 - European Commission

Chapter 4: Documentation ... Good documentation constitutes an essential part of the quality assurance system and is key to operating in compliance with ...
Read more

Developing good academic practices - s3.amazonaws.com

3 / 1 8 2 0 5 D e v l o p i n g d a c m r t s: 6 W h y u? ­ O L U * A P B h t p: / w. o e n d u l a r c i ­ g y v m s « 1 2 ...
Read more

Good documentation Practices - San Mateo County Community ...

Good documentation Practices. Title: Good documentation Practices Author: SMCCCD Last modified by: Nick Kapp Created Date: 10/23/2006 11:18:00 AM Company:
Read more

Guidelines for Developing Quality Documentation

Approved: 02.06.2010 Version 1.2 page 2 of 39 Acc-G-03-Q-Documentation Guide Status: FINAL 04.06.2010 Guidelines for Developing Quality Documentation
Read more

Create a Process Documentation Guide: Developing a ...

Create a Process Documentation Guide: Developing a Template That Can Be Used to Document Any Process
Read more