Can’t I use the people who developed the product?
You could, however, they are unlikely to have the experience or training to produce documentation that is useful for the intended audience. They are very knowledgeable about the product, literally knowing it inside out, however, this can be a disadvantage when documenting it. There is a possibility that they will make assumptions that the user has an equivalent knowledge of the product and omit important information as ‘it’s obvious how this works’. Professional communicators, on the other hand, do have the skills to pitch the documentation at a level appropriate for the intended audience without patronising or confusing them, whilst at the same time including all necessary and relevant information.
Additionally, particularly in software development projects where development tends to be done in modules, it is unlikely that any one developer (or team of developers) has sufficient knowledge of the system as a whole. This is where Technical Communicators can be of great use. They need to understand how the product works as a whole (without necessarily understanding it in great depth) and can produce documentation from a user’s perspective (‘top-down’), rather than from a system perspective (‘bottom-up’). As part of the development team, Technical Communicators can also advise on certain aspects of the product, in particular, the User Interface. They can spot inconsistencies of interface behaviour or wording and suggest changes and improvements whilst the product is being developed. Also, if on-line help is being produced, they can work closely with the developers to ensure that the help files are correctly integrated with the product.
This leads to a very important point. To succesfully produce documentation or other information products, it is vital that Technical Communicators are assigned to the development team as early in the development lifecycle as possible, even as early as Requirements Capture. This ensures that they can foster a close working relationship with other project members and gain an increasing knowledge of the product as it passes through the various stages of development. It is almost impossible to produce useful and usable documentation if it is treated as an afterthought and done as a last minute rush as the product is almost going out of the door.
As part of the development team, Technical Communicators have an equal role to other members. Please treat them as equivalent professionals and respect their skills. Don’t use them to minute meetings or perform other secretarial duties.
So, to summarise:
- Use professional communicators to develop all user documentation for your product
- Get them involved early.
- Keep them informed throughout the development.
- Don’t make life difficult by producing the documentation as a last minute rush.
- Treat them as equal to other project members (we are not secretaries!).
By following the above advice, you should be able to produce documentation for your product that is useful, usable, and complete. This enhances the quality of the product and leads to fewer support calls and can reduce adverse customer feedback. Wins all round!
Simon Butler FISTC MBCS
26th April 2006