How to help engineers produce technical documentation
As discussed in my previous post, technical writers are a vital part of any team. They focus on creating documentation that helps users experience the product more autonomously. However, as also discussed in that same post, regardless of having technical writers, engineers/developers still need to write documentation for more technical audiences.
At Feedzai, we have technical audiences, such as support teams who specialize in configuring the end-users’ product. Although not being a client per se, these support teams are usually the first users of the product and are the ones that are in direct contact with our actual clients. So they must have all the tools to show the product’s quality to our clients.
A few months ago, I started working with one of Feedzai’s product teams. After a few weeks of working with this team, I realized that our engineering team received daily requests from the support teams to help them configure the product’s different features.
Why don’t they use our documentation? Everything they need should be there, right?
It should, but it wasn’t. This product’s documentation was more significant and complex than the documentation that I had seen while working with other teams. Also, this particular product team hadn’t had a full-time technical writer for a few months. Naturally, the documentation got a bit out of control. In some cases, there were undocumented or partially documented features. Some elements had complete documentation, but it was in the wrong place; no one could find it. Others were documented in a way that made it hard for the support teams to follow.
How can we create documentation that is useful to the support teams?
After informal talks with the engineers, I sent them a short survey to help me understand the issues they faced when creating documentation for the support teams. The survey had these questions:
- What are your difficulties when you need to produce documentation?
- (Regarding the revision from the TW) Does it give you the necessary info to improve your documentation?
- Is there anything that you think could help you produce better documentation?
The results were clear:
- 72.7% said that they didn’t know where to put the documentation.
- 27.3 % said that they didn’t know what content needs documentation.
Taking these results into account, the answer was obvious.
We need better guidelines.
Feedzai has 500+ employees. This means that we have a lot of engineers spread across different teams, products, and regions. To have equally efficient and consistent work pipelines, we have a lot of guidelines and policies for various processes. Consequently, when I started this guideline, I didn’t want it to be another complex document that no one really wanted to use. This new document needed to be simple and straightforward.
Based on the survey results, I divided the document into four sections:
- Who should create specific documentation? For example, what documentation should be created by engineers vs technical writers?
- When should the documentation be created? We looked to specify the key moments when documentation should be updated.
- How should the documentation be organized? The checklist provided examples of the most common developments and where they should be documented.
- How should items be documented? We explained how to document each of the sections and deliverables by specifying what each section should and shouldn’t include, and by adding some good examples from the existing documentation.
This way, engineers could use the table of contents to go directly to the section they needed without going through the entire document.
Creating this document turned out to be even more useful than we initially thought as it allowed us to discover inconsistencies in our current documentation, which led to useful team discussions within the TW team.
After a few weeks, we reached a version that we could share with one of the engineering teams. Since they are the ones who will use it, we want their feedback for an interactive process that leads to the document being continuously improved. Ultimately, we want to know if the document indeed helps us improve the documentation delivered to support teams.
Once we receive their feedback, the next step will be to understand how we can extend this initiative to other engineering teams across Feedzai by answering questions such as:
- Who is the target audience for their documentation?
- Does their audience have any other specific needs?
- Does the team have different documentation deliverables?
- Does the team have the same documentation deliverables but with a different purpose?
- What do their engineers feel when they need to produce documentation?
After answering these questions, the focus is to extend the document so that it covers all the relevant cases.
To sum up, if you are working closely with engineers, always remember that they are not technical writers and usually don’t like to produce documentation. Make sure that they are part of the process, and help them succeed. That’ll pave the way for a happy team, and consequently, a happy customer.
