Sharp Words

In past posts, I’ve mentioned that information gathering is one of a technical writer’s more essential tasks. Here, I’m going to discuss some of the possible sources for information about the product you’re documenting.

Requirements and specification documents
Some companies produce requirements and specification documents when developing a new product or piece-of-product. In my own experience, when these are written well, they’re invaluable for the technical writer – they contain information about what the product is supposed to look like, and what it’s supposed to do and why and how.

If you have to write a brand-new document (or bit of document) about the product, then these documents should be your starting point for estimating how long it will take, and for drawing up an outline of the information to be included.

Information about bugs
It’s important to have access to the database in which details of issues/incidents are stored, where possible. This means that you can see what bugs have been fixed in the product and determine if and how the fixes might affect the documentation. Some companies will have a system where faults in the documentation are logged as bugs, too, which is a useful way of tracking your own work.

Engineers
Always, always, make sure you have access to the engineers (software or hardware) who have worked on the product. They are your primary Subject Matter Experts (SMEs), and therefore the people best placed to give you the low-down on how the product works.

Developing a good relationship with engineers and their managers is important too – they are also the people you will want to review your documents for technical accuracy. You need them to understand why the documentation is important and to be willing to give you their time and assistance.

Testers and support staff
Anyone else who has worked with the product, such as testers or technical support, can also give you a lot of insight and help. They generally use the product as a customer might, which means they can give you that point-of-view you might not otherwise have access too. In addition, they will often have documents of their own which can be used (test cases or FAQs, for example).

Playing with the product
No matter how much ‘paper’ knowledge you have of a product, and even if you’d been on the receiving end of demonstrations, nothing beats having practical knowledge of your own. Wherever possible, make sure you get a copy of the software or a model of the product to work with – it makes writing descriptions and procedures so much easier!

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts