Technical Writing Means Cooperation
Once upon a time, I typed a Chinese poem sentence in the Teams chat box to a Spanish colleague. She read the sentence seriously and carefully, and then asked me for the meaning. The sentence is 不知庐山真面目（bù shí lú shān zhēn miàn mù），只缘身在此山中(zhǐ yuán shēn zài cǐ shān zhōng)。The meaning is that one person doesn’t know the true scene of Mountain Lu, because he is in the mountain. If I stand in a big mountain, I spend time to walk through the different parts of the mountain, and then I only know some parts inside of the mountain. But I still don’t know the mountain from an outside view because I didn’t go outside of the mountain.
We can see the similarity during software development. A product is generally created and developed by several teams. In each team, there are programmers and testers. A team member usually focuses on finishing his or her task on time, writing code or testing a certain function. But a technical writer reviews the product or function in a totally opposite view. The technical writer studies the function from outside to inside, just like a normal user, sometimes in a global view, and other times in detail orientation.
Even we know the mountain or software product clearly, can we describe it clearly to others, and let the others know the mountain or software easily? This is a big question. Technical writing means cooperation. Nobody knows everything. The technical writer needs to collect information from different people or from different places. We call it information input. Good inputs come from the input provider who:
- Knows the product or function the best
- Verifies the product or function directly or indirectly
- Knows the structure of related documents
- Knows the target readers
- Has enough time to provide the inputs
We can consider the input provider as a role rather than a person. A technical writer can be an input provider, can train input providers, and can communicate with the input providers. An input provider may be an engineer, an IT support personnel, a tester, or a salesman.
The following information should be communicated to or confirmed by the input provider:
- Are all or partial inputs are received?
- What is or may be wrong, or may mislead readers in the inputs?
- What is missing?
- What can be improved for better user experience?
- Documentation impact and delivery phase
- All others related to documentation