Engineering Leaders, be the Chief Documentation Officer (CDO) on Your Teams

I define a Chief Documentation Officer (CDO) as someone who champions proper team documentation. CDOs are excellent curators of thought and great authors who enjoy documenting technical and non-technical artifacts. Deeply embedded in their DNA is the sense to give back and to teach.

A Chief Documentation Officer (CDO) is the ultimate steward of great team documentation

Why is improving on the knowledge base of your team important? I can cite the following five reasons:

1. To facilitate scale
2. To define your team’s identity and culture
3. To democratize knowledge and reduce the risk of silos or knowledge fiefdoms
4. To improve upon the knowledge base of your team
5. To improve team morale as This Harvard Business Review article states that the manager influences 70% of the variance in team engagement and performance.

While acting as a self-anointed CDO, here is one simple, yet effective tactic I employ. I seek a low-hanging fruit such as resolving a security vulnerability. While taking on this task, I do not initially ask for help, instead attempting to leverage existing team documentation to guide me through this task.

Oftentimes, steps to onboard onto the team’s development process or complete a given task are not clear, are outdated or out of order. As a CDO consuming this technical content, your job as part of the completion of the existing task is to make the document better. The Boy Scouts Rule equally applies here! Earn your title as the Chief Documentation Officer (CDO) on the team by setting the standard on what comprises good documentation.

Now, what comprises good documentation you may ask?

From my experience, here are some qualities that contribute towards good technical literature:

1. Content that is written with clear prose, telling the reader a story
2. Content that leverages images whenever possible to provide additional clarity
3. Content that takes into consideration the target audience
4. Content that allows for incremental consumption and knowledge acquisition
5. Content that includes external references for further studies

Let’s dive into each of the above qualities:

Writing with clear prose, telling a story

Your technical story should be concise, getting to the point and written with clear prose. Sometimes you may need to provide context but make an effort to get to the point while telling a story. As in any story, there is a theme, setting, plot, conflict, and conclusion. Ensure your story contains at least these main parts.

Leverage images whenever possible to provide additional clarity

Pictures are often worth a thousand words. Always leverage diagrams and images where necessary to communicate ideas further. For example, instead of attempting to describe your on-call procedures in many words, or a specific error scenario in a product use-case, take the time to draw a flow chart to include into the document as indicated below:

image capturing a error use-case

Consider the target audience

An effective communicator has taken time to study their audience. Therefore, it is very important to consider your audience while crafting technical literature. Oftentimes, engineers write the document for themselves, not paying close attention to the intended audience. They may write a technical article making assumptions about the existing knowledge of the team members. Such documents are often harder to read or comprehend when the target audience does not have the prior assumed knowledge. And similar to writing code, engineers should be educated on this fundamental lesson on technical writing, that stipulates who the audience is. It is not the author. It is everyone else.

Factor in incremental consumption and knowledge acquisition

Most internal technical literature has a set of steps required to accomplish a task. You have a great document if these steps are accurate and reflect today's technical landscape. However, the technology landscape changes rapidly and to guard against these rapid changes, it is equally important to capture why a certain step is needed in some cases. Why is this important?

If a step is inaccurate due to an outdated tool, 3rd party library that is no longer maintained, or updated processes, providing the why empowers the reader to seek for an alternate approach that would yield a similar outcome. In addition, the reader could potentially be learning something new while completing a task. You as author would also be contributing to a culture of caring by sharing, coaching by teaching, providing better meaning to the work of your teammates, increasing engagement, overall team performance and team cohesion. These are attributes of high performing teams.

Provide external references for further studies

There is no shortage of opinionated content in the software industry, such as this blog itself. Oftentimes, these opinions are not from the original thought leader themselves but are iterations thereof. In this case, providing an external reference to an opinion gives the reader further study material for exploration into the specific subject. References further add credibility to your writing.

In summary, technical leaders should be the chief stewards of their team’s knowledge base, earning the title of Chief Documentation Officer (CDO).

Leaders should take advantage of opportunities to improve upon team documentation with a keen mindset on increasing the team's cumulative technical knowledge and depth. When reviewing documentation, set a high bar on quality using a few of the metrics above. As the team continues to spend time understanding the why, as this is being captured as part of the story, they gain additional knowledge that would add to their personal growth, increase long-term productivity, and give further meaning to their work while adding business value.

I’ll wrap up this article by stating this obvious:

A thorough technical document can also pass for good accomplishment during sprint demo, as it captures knowledge that leads to better product decisions thereby adding business value.

Therefore your work as self-anointed CDO is never in vain.

Happy documenting.