A Technical Writing Workshop for Developers

Context:

Following the successful introduction of the Doc Quality Review process at Intel, I trained our team of writers on the most essential guidelines that could improve content quality.

This training was also very well received, and we wondered, why stop there?

Not all product teams had dedicated writers. Often, we received requests from those teams to create documentation, and we could not take on the additional work. But if we could educate those teams to write good technical content, we would make them self-sufficient.

That is how we decided to conduct a technical writing workshop for developers. Since I was our team's de facto quality champion, I agreed to prepare and conduct this workshop.

The Work:

Before I started creating the material for this workshop, I wanted to connect with my target audience and find out what they wanted to gain from it. I surveyed over 100 developers, application engineers, consulting engineers, quality leads, and engineering managers. I wanted this workshop to benefit anyone who creates technical content, regardless of the size of that content.

Based on the responses to my survey, I organized my material to cover:

• The basics of technical writing
• Procedures
• Reference information and README files
• UI and command line content
• Errors, warnings, and informative messages

Nearly everyone who responded to my survey asked to see lots of examples. So I made sure to illustrate every guideline with examples of correct and incorrect application.

Additionally, I wanted to create a reference that my audience could bookmark and use whenever they needed a refresher. I created a web page with these guidelines and a small selection of examples. I attached my presentation and a recording of the actual workshop for the benefit of anyone who wanted to learn more.

Result:

Nearly 100 people attended this workshop and found the content useful. Developers applied these lessons to their work and the quality improvement was obvious from the content reviews I completed subsequently.