Testing products to document them.
The technical writer cannot create useful documentation for the company’s customers by merely compiling information from various stakeholders. Serving as an advocate for users, the writer must test products in conditions similar to those encountered by users.
A Chinese tale tells of a group of blind men encountering an elephant. Each had a different perception: one who held a leg thought it was a tree, another who held the trunk mistook it for a snake, a third who held a tusk saw it as a spear, and the one who touched an ear considered it a fan.
Tale of the Blind Men and the Elephant
When a technical writer asks stakeholders in the company what a product is for and how it works, they might find themselves like the blind men asking what an elephant looks like. For R&D, it’s a piece of well-crafted code; for marketing, it’s a product to outshine competitors; for technical support, it’s an executable with bugs to fix, and so forth.
To obtain a realistic understanding, technical writers must explore the product independently, forming and then comparing their own opinions with others in the company. They are pragmatists, focused on practice over theory. Consulting exclusively with developers might lead to unsatisfactory user documentation:
- Developers often have an idealistic view of how their product should function, which may not match real-world performance.
- Information is often lost between:
- Developer’s knowledge,
- Developer’s communication,
- Technical writer’s understanding,
- Technical writer’s documentation,
- User’s comprehension.
By directly testing the product in user-like conditions, the first three sources of information loss are minimized. To address the last two, writers must filter, organize, and present the information in a manner suited to the distribution medium and the audience’s technical expertise.
Initially, such an approach might seem unusual within the company and could face obstacles like setting up a test environment. However, it is usually only after customer feedback or product reviews that the value of this method is truly recognized. Then, technical documentation is appreciated not merely as a necessary task but as a genuine value addition.