Design Article
The documentation challenge
Bob Widman, customer support and documentation specialist, Oasys Design Systems
5/3/2010 8:14 AM EDT
Examples can come from many sources, including product demos, R&D, training labs, Product Assurance regression tests, and customer case studies, though using customer materials requires their permission and removal of any proprietary information. The field team creates demos that can be leveraged, as does training and other groups. Unfortunately, this repurposing does not happen as often as it should with many companies.
3. What documentation product should the company use?
The following issues need to be considered:
a) What types of documents?
Many CAE companies use Framemaker for manuals often done as books, with tables of contents, indexes, and links. Powerpoint or an equivalent is often used for training slides because of the animation. Some writers use Word, a plain text, or html editors. The cost of the documentation tool is not as important as how efficiently a writer can create and maintain the documentation. Of course, he or she needs to be proficient in the documentation tool.
b) What output format?
Most documentation output today is in pdf and/or html formats. If you output both html and pdf, you should strive to use the same documentation source for both. This is often accomplished by using conditional tags in the documentation source files and/or using a pdf or html translator. By embedding complete tested examples into the documentation and making only the key part of the example visible, the accuracy of the examples will improve.
4. Engineers and support are too busy to provide the writer with details of new features and cannot find time to review documentation.
Making a sale and getting the software completed will always be a higher priority for the company. A documentation writer often understands and can run the product, which means that he or she will need less input and can do more on their own. Writers should be encouraged to work with training course and regression test developers since they all need the same information. The Engineering or Marketing Department will be able to provide a product functional specification of new features. Updated product demos and other marketing documents can offer information as well. Or, writers may be able to attend an internal new feature training classes for the field.
Getting feedback in a timely fashion can be a challenge, and some engineering teams are better at providing it than others. This is where writers need to be aggressive and use the department manager, if necessary. For an engineer that can't make the time to provide feedback, don't count on them and use someone else.
5. Should documentation take into consideration all end users?
It is often difficult to develop a User Guide useful for a large percentage of end users, since they may use the product in a variety of different ways. For instance, a synthesis tool may be used for a processor, graphics, wireless, communications or other application.
Additionally, everyone has a different experience and level of education. Documentation can never cover every use, even with specific examples for different targeted markets and multiple user guides for different experience levels.
The target of the primary documentation should be a typical user and should include an introduction with basic concepts for beginners. Even by documenting all of the commands and menus of the product in the reference manuals, it may not have fully explained how commands or menus are used together to describe a flow of what the end users want to accomplish.
Conclusion
Many companies overlook the importance of quality documentation developed by seasoned technical writers. Good documentation should be the cornerstone of product development, helping to create a positive corporate image and setting as a priority customer support and service.
About the author:
Bob Widman is a customer support and documentation specialist currently working as a contractor for Oasys Design Systems. He has more than 20 years experience managing and building Applications Engineering, Customer Support, Training and Technical Writing teams. Widman holds an MBA degree from New Mexico Highlands University and a Bachelor of Science degree in Mathematics and a Master of Science degree in Electrical Engineering from the University of Nebraska-Lincoln.
|
|
|
|
|
