How and Why We Improved Our Technical Writing Skills

#writing #agile #developer #career

We are a small developer team at Hanley Wood, which means that we don’t have a dedicated Technical Writer. On any given day, we may be required to write some technical documentation. Our most common include:

User Story Requirements
Test Instructions

However, occasionally, we‘ll need to write technical documentation for readers outside our core team, such as API documentation and How To’s regarding how to use new features within our Content Management System.

Why was it imperative for us to improve our technical writing?

When you lack technical writing as a skill, your writing could cause misunderstandings with your readers. Without such training, it’s easy to lose sight of your audience and write in such a way that it may be confusing to them. Being proficient in technical writing ensures that you’re able to take technical jargon and concepts, and concisely communicate them for the general audience to understand.

Why Technical Writing Skills are Needed to Write User Story Requirements

Poorly written User Story Requirements can result in a failed product. Capturing the requirements from the stakeholder requires a clear understanding of the user’s wants and needs.

According to Amber Israelsen’s course, “Technical Writing: Documentation on Software Projects,”² each requirement should possess the following nine characteristics:

Cohesive — address one and only one thing
Complete — fully stated at once, no missing information
Consistent — doesn’t contradict any other requirement
Atomic — doesn’t contain conjunctions
Traceable — meets all or part of a business need as stated by stakeholders
Current — has not been made obsolete by the passage of time
Unambiguous — concisely stated without jargon, acronyms, or esoteric verbiage
Specify importance — specifies a level of importance
Verifiable — implementation can be determined through inspection, demonstration, test or analysis

Fortunately, our User Story Requirements are usually well written, but as with anything, there is always room for improvement.

Why Technical Writing Skills are Needed to Write Instructions

In my experience, writing a set of instructions may seem simple on the surface, but once you consider your audience may not have the same knowledge or skill level as you, it’s easy to miss adding key details.

Below is an example of the type of test steps we commonly wrote out vs. how we’ve improved our writing.

❌ Bad Test Steps:

Navigate to an article
Verify that the headline appears

✅ Good Test Steps:

Navigate to an Article content type in the CMS
Note the value in the headline field
Navigate to this same article on the frontend via its URL
Verify that the headline is the value set in the CMS

The problem with the “Bad Test Steps” is that it was confusing for our developers who didn’t frequently use the CMS. Questions that would get asked were:

“ Go to the article where? On the actual website? In the CMS?”

“How should the headline appear?”

The “Good Test Steps” give more precise instructions that we are testing the frontend of the article and where to find the data we’re looking for in the CMS.

How did we go about improving our technical writing?

Once we declared there was a need for us to improve our writing skills, we set aside time in 2 sprints to complete a couple of Pluralsight courses that went over technical writing:

Writing Process Instructions and Directions
Description from Pluralsight: “This course covers writing an introduction to a set of instructions, managing safety warnings, formatting and presenting individual steps, analyzing the audience and situation, working with visuals, and developing a troubleshooting section.”
1h 29m
Technical Writing: Documentation on Software Projects
Description from Pluralsight: “This course covers the fundamentals of writing effective software documentation. Whether you need to document requirements, architecture/design, code, test plans, or manuals for end-users, this course gives you tips and best practices to do it all.”²
3h 48m

During our retrospective after each sprint, we discussed what we learned from each course. We found that the course material helped us to understand the importance of technical writing and knew how to apply it to our everyday writing. As a result of this training, we are more aware of the consequences of poor technical writing and aim to use this knowledge to write better documentation.

Conclusion

Overall, we aimed to improve our technical writing skills to strengthen our collaboration with one another and minimize confusion amongst our team members and colleagues.

Do you think your team could improve their technical writing skills as well? Check out the courses below in addition to the Pluralsight courses mentioned in this article.