In the numerous teaching/software/writing jobs I have worked with, I have encountered several life-changing learning experiences. These experiences pushed me into situations to provide an optimal service for my customers, fellow developers, and “students” alike. Over time, they have helped formulate a set of philosophies that I live by whenever I am in a technical writing position.
Philosophy #1 — Minimize Wordcount & Maximize Ideas
To this day, I still remember my grade 11 teacher telling me that “she doesn’t care how many pages it is, she cares how many ideas are on there”. Fast forward to my undergrad design courses, our professors emphasized on the importance of concise writing when expressing our ideas. Hence, when I was assigned to be content “rewriter” for my team, I opted to cut down my teammate’s content by half of the original wordcount, being cautious not to unintentionally remove the original ideas. This led to a lot of success for my team by being able to express numerous ideas despite our narrow word limit. When the TA reviewed our technical documents, the most concise sections received the most amount of positive feedback.
Even in a professional setting; the audience are rarely interested in too much content. They are interested in getting what they need as efficiently as possible, so they can proceed with whatever else they need to do. Hence, they have this implicit expectation that whatever information they need, should be given to them in the straightforward and quickest way possible.
Hence as a Technical Writer, I always aim to use as few words as possible with the most number of ideas expressed.
Philosophy #2 –Maximize Personal Involvement & Minimize Development Involvement
When I was interning, the initial work given to me were numerous changes throughout the entire documentation. In theory, the work was seemingly straightforward: contact the right Subject Matter Expert, get their feedback, and make the changes. However, doing the task itself was another challenge. There is a huge hidden diplomacy part of the job I wasn’t aware at first! The Subject Matter Experts didn’t like being interrupted unless absolutely necessary!
I took a different approach. First, I learned the jargon and ideas the Subject Matter Expert would’ve normally told me themselves. I did this by reviewing and reading up on with whatever resource that was available. Second, when I reached an acceptable level of competency, I drafted a proposed list of changes that would be made into the documentation. Third, I then sent this before & after change to the developer for either approval or feedback. Finally, developers would often give the approval, or I would then incorporate their feedback before adding it into the documentation.
This approach was very successful! The previous approach where I consulted them regularly and kept on interrupting them, really annoyed them a lot. This new approach only required them to just give a quick “yes”, or a quick “no, you’re mistaken, change it to this”. To further demonstrate the long-term success of this technique, as I independently master the material myself, I needed to consult the Subject Matter Expert less and I became the Subject Matter Expert myself.
Hence as Technical Writer, I always try to learn what I need to write first, and contact the Subject Matter Expert as the last resort.
Philosophy #3 — Be The Interpreter/Bridge Between Teams
In some of companies that I have worked in, lack of communication between teams could one of the biggest barriers to that company’s success. To resolve this issue, I held weekly meetings to check in with each different team to see if there are any new interests, concerns, or misunderstandings they like to share so I can resolve the issue for them. By understanding each team’s struggle, I essentially acted as a mediator and a messenger for different teams to smooth out any lack of communication that different teams are having with each other.
Then to break through these barriers, I also created internal documentation for every team. As each team came from a different background, industry-specific knowledge was very difficult for other teams. Hence, I filled in the missing gaps that different teams were having when communicating with each other. When these communication barriers are broke, different teams were able to synergize with each other better. Work became much smoother for everyone in the team and the customer receive the best quality of care.
Hence as a Technical Writer, I now try to understand the goals, ideas, interests, concerns of each different team.
Philosophy #4 — Test the Software Before Writing The Documentation
A common dilemma that software developers and technical writers experience when working together is synchronizing what the software do and what the documentation claims the software does. Inconsistencies on the accuracy of the documentation do happen due to lack of sufficient communication between the teams.
Hence, to address this issue and pay due diligence, I always learn how the software operates myself before I start any writing. First, I test the software does what it’s supposed to do, along with any implicit prerequisites the software needs or any unintended functionality it may perform. Then when I have confirmed for myself that it does what it’s supposed to do, I write down exactly what the software does, along with any implicit ideas I believe the user may need to know about. Verifying the software and writing the documentation myself ensures I catch any inconsistencies between the two teams to provide the most accurate, up-to-date information.
Hence as a Technical Writer, I always understand and test the software first before writing any documentation.
Philosophy #5 — Incorporate images & videos whenever relevant
The famous adage “A picture is worth a thousand words” still applies to today. Even when documentation is presented in the most optimal way, some readers without sufficient background could still be confused by advanced content. There are implicit knowledge gaps that the user may be experience that I as a writer sometimes may need to give them some extra support in. A screenshot or a video that demonstrates the usage of a product sometimes clarifies much more ideas and at times, completely replace the need for a new documentation article at all.
Hence as a Technical Writer, I always add pictures / videos to the documentation whenever possible in assisting the reader.
Philosophy #6 — Customer pain points are the ultimate feedback of all documentation
The reason behind all documentation is to tell customers all the relevant knowledge they need to know about the product but also hide what they don’t need to know. The issues faced by management is that companies do not always know what the customer needs to know and do not need to know. Likewise, the customer sometimes themselves are not aware of what they need to know and do not need to know. The ultimate challenge for management is isolating the thin line between what to tell the users and what not to tell them. Give the customers too much content, they get confused. Too little, they also get confused.
However, there is one way to check exactly what they need : the customer complaints.
Behind every one of customer’s complaints, there is an indirect need for documentation. During idle time, I would crawl the internet for all the possible complaints that customer may have. The more frequent the same type of complaint gets raised, the more it becomes obvious customers are having issues with the documentation if they’re asking the company directly for help.
Hence as a Technical Writer, I regularly check the voiced frustrations and complaints of the customer community for ways to improvement the documentation.
