Tuesday, 20 October 2020
Emma Garland
15 minute read
We write a lot.
As a software company, Rock Solid Knowledge produces a lot of technical writing. This includes articles, user guides, installation processes, proposals, API specifications and emails.
We host two key sites, our own site, and IdentityServer, an official partner site. Before 2019, when we needed to write something technical, the outcome was varied. Different writers would create content in our content management system (CMS), Umbraco. Authors would publish the article with minimal review. The articles, while always interesting, sometimes:
Everyone was trying to write to their best ability, but there was no formal structure, content standard or review approach.
Imagine if we did this with our code:
It gives me shivers writing about it…
Getting time to write articles was not always easy. People might become inspired by an idea and set about writing about it, either in their free time or in between waiting for builds. A hopeful article might fall by the wayside due to deadlines and become too out of date to publish. Or, the article had potential, but lacked the structure needed to get it into a palatable format.
For client-facing colleagues, we risked irritating our customers with abrupt sounding replies, accidental typos in presentations or helpdesk tickets that could come across as confusing. Each issue could impact in its own way, costing time, reputation and potential work.
Poor quality has a negative impact on your brand. You soon get a bad reputation in the software industry for putting out low quality and inaccurate code. When it comes to external content, the same rule applies.
With an article, by the time search engine robots index the content, it stays out in the wild forever. If the article is poor, it could damage a brand. Good enough, and it gets turned into a Google Featured Snippet.
The same applies with proposals and pitches. Have you heard of people who throw away a CV if they find one typo? Imagine if this was a pitch for a new app or website asking someone to spend money on your company, and there is a glaring error in the giant company slides. It doesn’t bode well for winning the pitch...
This isn’t a problem unique to us. In GitHub.com’s Open Source Survey 2017:
This tell us that while technical documentation is important to open source users, they seem to avoid writing it. But why?
Left with a lack of procedure, people start to invent their own standards and processes. Or they fear starting a task at all with no framework to work inside. Sometimes you don’t know where to start. You’re an expert in your domain but getting that out on paper isn’t as simple as editing a brain dump. For us, what could take a few days rolled into weeks as writers struggled to get their thoughts into coherent pieces. We needed to learn effective planning techniques to get the articles published before they became obsolete.
We have a different website audience on IdentityServer.com than RockSolidKnowledge.com and it is important that we keep both audiences happy. The more readers share our articles, the wider the reach, meaning more potential customers or employees landing on our sites for the first time. But how can companies write articles that readers want to share if they don’t understand who they are writing for?
Learning how to use a suitable level of jargon for the audience can be tricky. Too simplistic, and people might not get that in-depth knowledge they were looking for. Too complicated, and people might turn away from intellectual intimidation. If you are writing about a new and complex technical integration, who are you writing for? A developer who will need to implement it, or someone who will buy your product for their developers to install?
While readers are browsing a site or app, they build an expectation of the tone and style of the site. Mailchimp has excellent examples of this in their style guide, especially in their section about voice and tone, noting “We’re never condescending or exclusive—we always bring our customers in on the joke”.
I found Mailchimp's help section is far less cheeky than their main site. The last thing you want when querying a bill is an eccentric, winking monkey.
Consistency is vital for reader confidence in a company. Before 2019, Rock Solid Knowledge hadn’t established a consistent tone or formality across our sites, which could confuse readers. One article on our sites might be colloquial and mildly sarcastic, and another might sound more like a cease and desist letter. It was clear we needed to incorporate the right level of formality per site.
Different site, different audience, different tone.
If you want people to find and share your content, it needs to be good. Google’s algorithms work to optimise high quality content, and they have shared symptoms of low-quality content in their Search Quality Evaluator Guidelines. We looked to improve our Search Engine Optimisation (SEO) by improving the semantic HTML and other metadata within our articles. The quality and relevance of the article content, along with a logical structure, will help influence a higher ranking on search results. However, the primary focus of the article should always be the user.
When buying any technical product, you usually expect some instructions. To get the most out of the product, you want instructions to be included in the packaging (unless you’re one of those “I don’t read the destructions” types). The instructions need to be clear and easy to read to encourage a happy user base. No-one wants to spend hours assembling a flatpack to find they have put the main panel in reverse, rendering the rest of the set of drawers entirely useless...
I also have a personal vendetta against recipes that lead you through hours of careful cutting and prep, only to interject halfway through with “Meanwhile, marinate the chicken overnight for at least six hours”.
Readers appreciate advanced warning.
The same applies to technical instructions for software. Clear and ordered steps, with prerequisites listed upfront, gives users the best chance at success, and hopefully means fewer issues raised.
As a company, it was clear we needed to take some steps to improve the quantity and consistency of our technical documentation. We could have written technical writing off as “not our area”. Writing articles could have continued ad-hoc, increasing the risk of poor quality. Our developers may never have learned more skills to optimise technical documentation. This might have saved some time and money on training, but would have led to:
Another choice was to hire a copy writer, paying for someone external to write regular content for us. But this would lose the sense of teamwork and pride that comes across in our own articles. We also would risk our quality and expertise being lost, especially in our area of specialism, the identity space.
A random option could have been to use machine learning to generate blog posts. If it was good enough to fool Hacker News, surely it would work for us? Well, surprise! I generated this whole article using an AI algorithm developed during our machine learning classes.*
*I jest, of course. Generated code snippets would be interesting…
None of those options felt right. We’re proud of our code at Rock Solid Knowledge, and maintain a focus on high quality through training, testing, efficient processes and peer review.
We wanted to mirror our emphasis on quality in our technical writing and make it something to be as proud of as our code. To enable this shift, we needed to grow the necessary skills and processes. Why not follow the same formula that works for code quality? Process, regular training, and peer review.
Find out in part 2 how this approach worked for us and could work for you too.
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
