How we have improved the technical writing of our teams (2/2)

In part one I discussed how Rock Solid Knowledge realised we needed to improve the technical writing of our teams. Now learn how we have worked hard to raise our writing standards up to the same level we expect in our code.

Training the team

To start to learn how to write clearly and concisely, a large group of us undertook technical writing training with Emphasis Training in August 2019.

We were shocked that the trainer did not allow us to use our laptops. Instead, we would be using pen and paper! The training followed an engaging, personal approach with shared stories, formal teaching, and booklets. The handouts included an excellent reference book “The Write Stuff” by Emphasis.

The trainer covered a lot in one session. I was pleased that we received individual reports analysing our own writing samples, highlighting areas for improvement. I hadn’t realised how often I was using the passive voice, but there were multiple areas in my writing where I should have used the active voice instead.

Active versus passive voice

Technical writing should normally use the active voice. The active voice uses the formula:

actor + verb + target

For example, “The cat sat on the mat” uses the active voice, but “The mat was sat on by the cat” is passive and has less impact. You could even omit the cat entirely with “The mat was sat on”. *

* I do not condone omitting the cat. Ever.

Technical writing classes

Since the training, I’ve been running fortnightly technical writing classes for people to keep flexing their writing muscles. Sessions have included topics such as “Active vs Passive Voice”, “The Four Ps of Persuasion” and “The Hero’s Journey”. For our homework, we study the Google Technical Writing Modules. These have proved excellent as bitesize modules that we can work on separately, discuss together and practice in class.

These sessions have led to creative new ideas. Talking about our own frustrations with documentation led to us building a glossary of acronyms on IdentityServer, which we can link to within articles.

Since lockdown, we have switched to running these classes online-only, which has fallen into a steady rhythm, much like the rest of our remote working practices.

Living guidance document

Sometimes all the advice, training and suggestions can become confusing and you need one place to get help from. We have created a source of truth in our living guidance document that holds:

• Tone advice for articles
• Practical guidance on punctuation, bullet points, title case etc
• Wider advice, like removing knowledge-assuming words (e.g. “simply”)

Minor changes to formatting and wording can make all the difference to creating a polished, professional article, just like style updates on a website.

Planning an article

Our articles first need internal sign-off by a director. We write into an article template that includes a few writer prompts, including an article summary and finding a suitable preview image. The template also lists the “Four Ps of Persuasion”, a useful technique for planning an article.

Split your article into the following four sections before you start writing, and you will find it easier to write concisely:

1. Position: Where are you/the reader now? What is the current state?
2. Problem: Why is the current position an issue? What are the problems with staying there?
3. Possibility: What are the different solutions to solve the problems? What are the pros/cons of each?
4. Proposal: What is the best way to move forward? Is it best to do nothing? Is there a logical conclusion?

In fact, I wrote this whole article using the Four Ps of Persuasion, two per part. Can you spot them?

Four step review process

We have evolved a Four Step Review process for technical writing. You can think of this as the process gates in a deployment pipeline when someone must sign off at each stage of a release.

The process applies to articles that we create in Umbraco, but could also apply to presentations, user guides and even important emails.

At the review stage, the author’s approved article template will help them structure their new article. We encourage writers to help reviewers by doing a draft read to catch initial typos and errors. Authors can help the look and feel of their article by finding images that add value to the article. Once the author completes their first draft, they get it approved with four review steps:

1. Technical: Send technical articles to a peer close to the subject (e.g. our expert identity team will check a security-related piece)
2. Writing: Send the article for a content review for grammar, language, tone, and spelling
3. Design: Add and preview the article in Umbraco, then ask a design peer to review layout and images
4. Director: Send for final director approval

Once each reviewer approves the article, the author schedules the article in Umbraco for publication. We now have a shiny, well-structured new article that has been through peer review from all angles.

Dedicated company time

We have dedicated company time to create and review technical writing. I spend about 15% of my time reviewing and editing articles. A few extra hours for a lot of extra quality pays off, just like writing tests for code.

If we have an article to write, we keep our project lead informed and plan in the blog writing time into our schedules.

We recently realised that we were heavy on articles in IdentityServer but low on articles on Rock Solid Knowledge. A group of us were selected to spend two dedicated days writing articles for Rock Solid Knowledge. In fact, in a meta twist, that is how this article was written!

I really enjoy reviewing and editing articles, and I’ve learned a lot from all the different subject areas that we cover; from Locking and async await to IdentityServer to Tailwind.css. It is the same as peer reviews in being a wonderful way to get to know another codebase.

I like my technical writing like I like my code

If you’re comfortable using developer terminology, try approaching an article as if it is a development task. Treat it with the same care and respect as you treat your code. The similarities are clear:

1. A scribbled down article idea on a napkin is a throwaway prototype
2. The article template is an architectural diagram
3. The “Four Ps of Persuasion” is the proposed workflow
4. The review process matches the code review stage, via a pull request or pair programming
5. The review is also a Quality Assurance (QA) stage, looking for typos and issues both automatically and manually
6. The design stage is like using Umbraco's preview mode to get a beautiful article layout
7. The publication of the article is akin to the development team working together to release a professional product

While writing our articles, we chat if we’re stuck or confused. This can unblock someone as much as the coding technique “rubber ducking” does.

How are we doing?

Technical writing is a business skill for life. Our developers are setup not only to code well, but to be able to write more successfully in future.

Look at our recent articles on Rock Solid Knowledge and IdentityServer and you can tell us whether all this effort has paid off!