Shwetha Madhan, VMware
April 15, 2020

When developers and technical writers work well together, they both take advantage of their relationship and bring out the best in each other. This article highlights the value of an efficient collaboration which can improve the quality of the documentation.

Although we don’t always think of developers and their relationship to documentation, in a real-world, documentation is as important to a developer as all other facets of development. Most developers spend hours not just writing code and designing a digital workspace, but actively engaging with the community and trying to learn new things. Developers must know how to communicate technical requirements and specifications to other stakeholders as they often contribute to content that goes in front of the customers. They must write clearly and concisely. The ability to deconstruct coding in simple words sets them apart. Developers have to explain technical terms and concepts in a way that makes sense to less technical team members. So, coding is not the only “unicorn” skill for designers and developers.

In a real SaaS-paced world, developers are often under pressure to develop new features and solve issues quickly. The rapid pace of a faster and better digital landscape means that product innovation occurs in days, not years. With limited time and bandwidth, writing in simple, plain language may not be the top priority for our developers. Their main area of expertise is not content development. Expecting a developer to always think like a writer and take the time to explain technical terms in simple language is easier said than done.

When writers wore an editor’s hat, we helped fix the symptom, not the cause

A few releases ago, our team of tech writers performed the role of a release note editors. We collated all the bugs written by our developers, made some grammar edits, turned it into a crisp summary, and added it to our release notes. Most of the time, the bug description required more than just a grammar edit. To rewrite the bug, we had to dig deep into the issue, read the underlying descriptions or inline comments, or reproduce the steps to write a simple one-line summary. We often found ourselves commenting, “need more information.” We spent more time than needed on each of the bugs as the bug title had too little detail written in plain English. Commenting in the bug tracking tool, asking for more information, with back and forth editing was not a scalable solution. Donning an editor’s hat seemed to be a downstream approach as we tried to fix the symptom and not the cause.

Data-Driven decision making

When we tracked the actual time spent editing and rewriting the bugs created by our developers, on average we found that close to 60% of the bugs required a complete rewrite. These bugs required in-depth editing and research. On average, each release, a release note writer spent close to 6 hours working on these bugs. The need to optimize resources is evident when the organization’s demands exceed the resources currently available – we simply did not have the time.

To address this problem, the information experience team for VMware Workspace ONE UEM took on the task of helping developers write better bugs and create a workforce multiplier that enables technical writers to take work off their plate. We began this initiative in 2018 and called the mission, Write Better Bugs.

Our Strategy: Upstream Solution – Treating the source of the problem

Developers are not necessarily trained as good writers. Should you always hire developers who are great writers? Or should writers always wear an editor’s hat and constantly edit what developers write? Both don’t seem to be scalable.

To improve the overall quality of your brand’s content, enable your community to write better.

The Write Better Bugs mission is a collaborative effort between the R&D and the tech writing community to help developers write more effective customer-facing content. The goal of the mission is to reduce the work for the tech writing team, eliminate the complexity that must be managed, improve our documentation quality, and get ready for automation.

Identify the business value of writing better bugs

Writing a good bug summary is a task often overlooked. A well-written bug summary doesn’t just save the resources of the company, it also creates a good relationship with our stakeholders. Writing clear bug titles makes the bug easy to find, helps identify duplicate bugs and makes triaging a whole lot easier.

The key business values are:

    • Stakeholder engagement
    • Fewer bug duplication
    • Better search
    • Faster turnaround for Release Notes

Working Together: Setting up a project for success

Step 1: Laying the groundwork

At first, we helped our developers understand what’s a high-quality bug – “The know-how.”

A good bug title is clear, short, and gives a summary of what the bug is. It must contain the category of the bug or the component of the app where the bug occurred and the action or under what circumstances it occurred. It should clearly explain the problem, not the solution. A good title must have information about the error message and a crisp summary of what went wrong, but not what you did to fix it.

Step 2: Training and Workshops- Drawing a comparison model

A robust training and development program helps to have a consistent experience and background knowledge.
Organizing workshops with good and bad examples can help to draw a clear comparison. Here’s how it looks:

Good Bad Ugly
A “500 Internal Server Error” message appears and the application closes. An unknown error pops up and crashes the application. Application crashes.
The Save dialog under File> Save fails to save your file. Save dialog does not work as expected. Unknown Save Error.

 

Step 3: Adhere to quality standards through a style guide

There are lots of benefits to having a style guide that helps fine-tune the content. A well-written guideline with useful good and bad examples is an easy-to-access plug-and-play information for our R&D team while reporting a bug. Our better bug style guide helps our developers understand the importance of writing better bugs, memorize the key principles, and compare what’s good versus what’s not.

“Golden Nuggets” of our Better Bug style Guide:

    • Keep it brief
    • State the problem not the solution
    • Plain language for all

Step 4: Our Trump Card: Baking the solution within the bug reporting tool

Workspace ONE UEM team uses Jira to capture, track, and resolve bugs throughout the entire development process. While our better bug style guide is a great plug-and-play asset with clear and useful examples of writing good bug descriptions, making the template within the bug tracking tool is one of our biggest wins. It helps our developers focus on the task at hand instead of refreshing the basics over and over. Here’s what the template looks like in our bug tracking tool:

 

Did it work?

Nothing works the first time. It took days of work, exploration, and discovery. Nearly every operating system contributes to this mess, and we knew the quality of our bug titles increases very slowly at first. We waited for a few releases before we tracked our success. We continued serving as “doc consultants” and helped our developers with the right feedback. With every release, our bug title rewrite effort is dipping down. As of today, we wordsmith only 10% of the bugs written by our developers.

Key takeaway: Help your developers become better writers; it takes two to tango!

Trends in digital design emphasize clean lines and few words–giving language itself more weight. And, more and more, we see content coming from a wider variety of sources. Learning how to write well isn’t an important skill just for the writers; it’s an important skill for everyone. The world of design and development can be very fast-paced and sometimes a mad scramble to get everything ready for release. A good relationship between the R&D and technical writers benefits not only both teams, as they learn and improve their skills, but also the company, as good content shows competency.

Writing better also helps you move one step closer to your automation journey. Many project management tools nowadays come with automation that helps in reducing manual interventions. Improving the quality of our bug titles can also help us move the needle towards automating our bug process.

In a world where everybody writes, it’s essential to make sure that we’re enabling our developers to do so as effectively as possible. In summary, for a win-win relationship, a technical writer should not settle for just being the receiver of information but should also help developers understand what could be improved. Simple, time-saving measures always help a team run smoother.