Friday, 23 October 2020
Emma Garland
15 minute read
If you are a developer, your role is not purely about writing code. Being able to write clear, professional technical documentation is vital in the software industry.
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.
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.
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.
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.
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:
Minor changes to formatting and wording can make all the difference to creating a polished, professional article, just like style updates on a website.
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:
In fact, I wrote this whole article using the Four Ps of Persuasion, two per part. Can you spot them?
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:
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.
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.
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:
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.
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!
Last updated: Monday, 19 June 2023
Senior Software Developer
She/her
Emma is a Senior Software Developer and multiple Umbraco MVP at Rock Solid Knowledge.
We're proud to be a Certified B Corporation, meeting the highest standards of social and environmental impact.
+44 333 939 8119
