Technical Writers Should Attend Code Reviews

Code review is an important part of quality software engineering, and technical writers stand to benefit greatly from attending them – especially if they are tasked with writing content for an audience of software engineers.

In a typical organization, code review is an opportunity for developers and engineers to share their work with peers, enabling them to examine code entering the code base and potentially catch any issues prior to merging. For the person presenting their work, it is the point where their work is explained in the most detail. For the people doing the review, it’s a chance to bring the best possible code into the code base.

It is an Opportunity to Learn More about the New Updates

For a technical writer, it is a rare opportunity to gain critical insight into the reasoning behind new changes coming into the project. You can gain a better understanding of not only how something works, but why the decisions were made to make the change in the first place.

Often, the most important part of technical documentation are the extra notes and information blocks that give the reader additional insight into how the product functions. This insight is available in abundance in code reviews.

Technical Writers Benefit from an Understanding of the Process

Knowing the complete software development process may not make the documentation you’re working on today better, but it could serve you in your future projects. Understanding how engineers in your organization bring their ideas from concept to realization.

The more a technical writers understands about the process, the easier it is for them to work with the engineers, product managers, and more.

Building Rapport with Engineers is Important

Technical Writers live in an interesting space in an engineering team. They’re usually the only non-management and non-engineer in the room from the start of a project to its end. Engineers appreciate it when someone not immediately involved with development takes the time to try to better understand the work that goes into creating the product.

For Technical Writers, developing that rapport with engineers is essential. You depend on them as sources for your documentation. Additionally, they depend on you to write accurate content.

Code review is an excellent opportunity to meet and establish relationships with members of the engineering team outside of general staff meetings and grooming sessions.

Technical Writers that take the initiative to better understand the product for which they’re writing are inherently better positioned for success. While they may never write a line of code themselves, understanding why specific decisions were made in the development process gives writers an advantage when it comes to creating clear and insightful documentation.

Leave a Comment