Posted by s.hettrick on 7 June 2013 - 8:55am 

By Craig Haiss, HelpScribe.

If you want people to use your research software, it needs good documentation. Many people employ the help of a technical writer to write documentation, but how do you get the best out of this relationship? We turned to Craig Haiss for help. He set up HelpScribe to share his ideas with the technical writing community, and in 2010 it was named one of the most influential technical writing blogs on the web.

1. Accept that no tool or process is as simple as it seems

The more functionality a tool provides, the greater the chances a user will become confused by features of that tool. Even the iPhone, with it's simple touch screen interface, has a 150+ page manual.

Do not assume that your research software or process is so simple that minimal or no documentation is sufficient. Doing so could cost you both time and money when research grinds to a halt due to unanswered questions or misunderstandings.

2. Decide whether you need a writer with domain knowledge

Sometimes too much knowledge can be a bad thing. If your audience has limited knowledge of your software or field of research, a writer with a similar level of knowledge will be able to anticipate questions. You may have to explain basic technical concepts to the writer, but the resulting documentation will be more thorough and user-friendly. For example, you may be frustrated when the writer asks you about the functionality of the clearly labelled Start button in your interface, but you'll be even more frustrated later if you have to explain it to hundreds of confused researchers.

Such a writer can identify jargon that may be confusing to your audience, and document the meaning of any technical terms.

For developer documents or advanced training guides, you may want a technical writer with experience in your field. Remember, many technical writers have experience in computer programming, training, sciences, or related fields. Such a writer will be able to understand concepts quickly and explain them to a technical audience in a clear and concise manner.

Choose your writer carefully based on the needs of your audience.

3. Pull your writer into the project early, and keep them informed

Your writer can draft content based on software design specs or early workflow discussions. This will help you hit delivery dates and improve the accuracy of the documentation. Many writers are familiar with agile development concepts and will adapt easily to such an environment.

Your technical writer can also contribute to the software design phase by offering guidance on user interface text. They can even offer ideas on how to embed user assistance into the interface. For process documents, your writer can act as a user advocate and step through that process, thus helping to identify gaps or flaws.

Remember, your writer likely has experience in usability, and can help you produce better software or a more elegant process.

4. Respond promptly to requests for information

The technical writer's primary means of gathering information is to ask questions. Sure, you may be able to provide them with specs, pseudo-code, fully-functional software, or a diagram of your research process. But what you haven't likely provided is context.

Remember, great documents don't just tell you how something works. They tell you why it works that way, and explain how to complete tasks based on that functionality.

Your writer will ask many questions about the tasks your researchers hope to complete using your software or documentation. Provide thorough answers when possible.

If you are not the person to whom such questions should be directed, provide the writer with a primary contact. Also, make it clear that this contact person understands they are responsible for answering the writer's questions, and that any requests for information should be answered as promptly as possible.

Sure, when things heat up it can be hard to answer every email request that lands in your inbox. But putting off such requests will become painful when your delivery deadlines are looming and you realize the documentation isn't near completion.

The writer will likely understand if you or the primary contact cannot take the time to explain something right away, but will be grateful for the name of another person who can, or even a link to a reference document that can serve as source material.

If you really want to get the best from working with a technical writer, provide them with use cases.

5. Try not to be territorial

If you have existing documentation, perhaps that you yourself have written, take a deep breath and just hand it over.

Yes, the writer will make changes. In fact, they may make drastic changes to the organization, detailed content, and even the scope of the documentation. However, these changes may result in a document that is more intuitive, accurate, and targeted to the needs of your audience.

If the writer makes changes that you completely disagree with, talk about it. Are these changes due to a misunderstanding of the content or its purpose? If so, any technical writer worth his salt will likely make revisions and improve the documentation accordingly. However, you should first ask yourself if your objections have a solid basis. Allow the writer to explain the purpose of any changes. Try to understand how those changes improve the effectiveness of the documentation.

6. Take advantage of the writer's knowledge of publishing

Discuss the audience you are trying to reach and the media formats commonly used by that audience. Have you considered swapping your stodgy PDF manual for a video or interactive tutorial? Or perhaps you'd like to single-source your content and ship it in multiple formats?

Remember, many writers have experience publishing content to multiple formats, and some are experts at content management. They should have a thorough knowledge of current publishing tools and can help you choose the best deliverables to communicate with your audience.