Working with a technical writer
Once a technical writing project starts, you need to manage it effectively. This page discusses some important topics.
- What does a technical writer need a client to do?
- How does a technical writer work with other people on a project?
- Where should the work be done?
- How are reviews managed?
What does a technical writer need a client to do?
During a documentation project, you are responsible for providing the following:
- Suitable information and training to ensure the technical writer has sufficient knowledge to use and document the subject matter. The quality of documentation produced by a technical writer is directly related to the quality of information that you supply.
- Guidance on any style guides and standards that need to be adhered to.
- A dedicated subject matter expert (SME) who can be contacted throughout the project to answer questions relating to the documentation in a timely manner.
- Access to the product under documentation.
- If appropriate, access to development workflows, ensuring that technical writer is included in communications relating to changes in the subject matter.
A freelance technical writer may be working on other projects and therefore will not be permanently available to answer unscheduled requests. Consequently, both you and the technical writer should endeavour to keep to the time schedules outlined in the initial contract.
How does a technical writer work with other people on a project?
Creating effective documentation is a partnership between you and the technical writer. Consequently, throughout the documentation process you can expect to have considerable contact with the technical writer. This contact can take many forms:
- Face-to-face meetings. For example, during the early stages of the documentation process, the technical writer may spend considerable time collecting information by speaking to your personnel. This process may involve extensive training if the subject matter under documentation is complex.
- E-mail. Throughout the documentation process, the technical writer will maintain a dialogue with you by e-mail. This dialogue may well include a steady stream of questions to ensure the accuracy of the documentation.
- Telephone. On occasion, it may be necessary for the technical writer to speak directly with you and your colleagues, for example to gain an understanding of concepts. It is good practice for the technical writer to follow up with a written summary of the conversation. All parties should agree that the record is accurate.
Where should the work be done?
Whether a freelance technical writer works in your offices or in the writer's own office depends largely upon the nature of the project. Sometimes, the technical writer will spend an initial period on site collecting information, and thereafter the requirements of the project will determine where the remaining work is carried out. Factors determining where work is done include:
- Security issues. Do security restrictions prevent information from being removed from your site?
- Remote access. Can the technical writer gain access to the product remotely?
- Access to your personnel. Does the technical writer frequently need to interview your staff?
- Presence during testing and building. If the documentation is to include details of the testing or building of the product, the technical writer may need to be on site to photograph or document the procedures.
- Access to illustrators. If the documentation requires illustrations, the technical writer and illustrator may need to work closely together during some periods of the project.
How are reviews managed?
Review processes vary depending on the project and on the technical writer. Therefore, ensure that the technical writer gives you exact instructions about what is expected during the review process. The process may involve a number of people, for example technical experts, typical users, etc, all of who will review the documentation from a different point of view. It is the role of the technical writer to incorporate review comments appropriately.
Generally, initial reviews should concentrate on technical content and document structure. Only when the content of the document is agreed should the review process concentrate on layout and phrasing.
During the documentation process, to help clarify any inconsistencies during the review, an audit of all communications between you and the technical writer should be maintained.
Finally, the time scales for the completion of reviews should be clearly defined and agreed between you and the technical writer. The implications of failing to meet review time scales should be indicated in the contract or terms and conditions that were issued at the start of the documentation project.