How we are driving up the quality of internal technical documentation at Volvo Cars — with just a few technical writers
Treating docs like code is part of it — but not all of it
There are many components to a great developer experience. One of them, I think we can all agree, is to have quality internal technical documentation. But how to get to that place? Few engineering organisations prioritise recruiting technical writers above software engineers. And software engineers, typically, and perfectly understandably, prefer to be coding rather than writing. The answer in the tech industry of today — is to find a way to scale tech writing.
Consider this…
Many years ago, when I was working as a technical writer at one of the world’s leading IT companies, the sacred ratio was one tech writer for 8–10 developers. Later, when I moved on and started working as a documentation lead in FinTech, I tried to get the company to implement this ratio — but, alas, it was never going to fly. We settled on about 1 to 30. I was not too pleased. If only I had known what was to come. When I started working in big tech, it was more like 1 to 1000. And now at Volvo Cars, it is — well that’s what this blog post is all about.
How just a few technical writers (two within a centralised developer experience function and one focusing on a specific part of the organisation) are driving up the quality of internal technical documentation among 4500+ software engineers at Volvo Cars. (What’s the ratio now, huh?)
As we’ll describe in this blog post, moving to treating docs like code is one key component of scaling technical writing, but not the only one.
Implement docs like code
About five years ago when at a previous company, I stumbled across Google technical writing manager, Riona MacNamara’s talk from the 2015 Write the Docs conference, Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture. Riona was talking about solving problems around internal technical documentation by treating docs like code. Before listening to this talk, I was just a ´normal´ technical writer. After, I was a man on a mission. We soon started moving towards a docs like code approach. We built the Backstage docs like code plugin TechDocs and the rest is history…
Here at Volvo Cars, the developer experience part of the organisation has brought in the open-sourced Backstage and along with that TechDocs. As more and more teams throughout Volvo Cars onboard to Backstage as their “single pane of glass” developer portal, we open the door for engineering teams to move to a docs like code approach through TechDocs.
With a docs like code approach, we lower the barrier to entry for engineers to write documentation. Engineers can use tools and processes with which they are familiar and interact with every day. Examples of these tools and processes would be GitHub, Visual Studio Code, and their existing CI/CD. Engineers can write their documentation using the widely-known, easy-to-use language for formatting plain text, Markdown. And engineers consuming documentation can find it in the same place as they find everything else in the software ecosystem, Backstage.
Treating docs like code is a fairly easy sell to developers. And this works in our favour with our aim to standardise on one tool for producers and consumers of technical documentation. You all know the alternative — proliferation of technical documentation in numerous places. Documentation fragmentation. Nobody can find what they need and if they do, they have no idea if what they are reading is up-to-date.
To add further value for our developers, we have added a bunch of extra features to TechDocs — last updated per page, diagrams as code with PlantUML and Mermaid, text re-use, integration with our Stack Overflow for Teams instance, and page reading time.
But docs like code is not the whole story. To scale technical writing and raise the quality of technical documentation, other tactics are needed.
Show off shiny examples
One of the first things we realised when we started our work to drive up documentation quality is that we didn’t have any shiny examples. There was nowhere to point when developers asked us: Can you show us an example of great documentation? This was clearly something we needed to prioritise.
But now the stakes are raised, right? If we are going to have a bunch of sites that we show off as shiny examples, we better be sure what standards we are following and how we want others in the organisation to set up their sites.
So, as we worked on our three shiny examples, we brought together industry best practice, our own technical writing experience and knowledge, and Volvo Cars context to get clear around what a doc site should look like.
Leverage industry best practices
When we started our mission to drive up the quality of technical documentation at Volvo Cars, we realised pretty quickly that we needed to move fast. And what better way to move fast than learn from industry best practice and leverage what’s already out there.
So far, we’ve used (and tailored for our use) the following:
- Topic types following the Diataxis framework
- Documentation templates from GitLab’s The Good Docs Project
- The Vale implementation of the Google Developer Documentation Style Guide
The pick of the bunch has been implementing the Diataxis framework (see pic below) with its topic types of how-to guides, reference, explanation, and tutorials. The framework is easily understandable and has served as a good foundation for getting our message across about quality documentation.
Define what doc quality means for you
An important part of our work has been defining what doc quality means. What does it mean in our context here at Volvo Cars with 100s of teams and doc sites. And many diverse types of software engineering, from in-car software to app developers to factory.
But how do you measure doc quality? I have been pondering on this for years. Do you send out a documentation survey to users of documentation? Or writers of documentation? Which criteria should be used (for example, readability, clarity, completeness, and so on — there are many)? Can we get some of the way with automatic check?
The clouds parted when I came across this excellent piece by Tom Johnson on his I’d Rather Be Writing site: Different approaches for assessing information quality
And the answer is: checklists.
Through Tom’s examples, we were able to build up a golden doc quality checklist. With that in place, we toned it down a bit and defined a silver doc quality checklist. And then, realising that it would be mainly the docs team that would be concerned with these still quite high-bar checklists — we toned it down even further to form a good-enough docs checklist.
And that’s what we have now. And it is good enough.
Have an empathetic approach towards your developers
I do feel sorry for developers — I really do. I’ve been working in the software industry a long time and still remember when software engineers just coded. I specifically remember one engineer holding out for several months against being involved with testing work — and even threatening to leave the company. Nowadays, as we all know, software engineers must do it all — being involved with coding, testing, DevOps, product thinking, and yes also — documentation.
Technical writers see it as part of our job to lower the barrier to entry for writing docs. We want to meet software engineering teams where they are in terms of their documentation readiness and give them what they need. We also want to help teams understand that documentation is not the solution to every problem and then make good decisions about what should be documented.
I have already mentioned that we use Vale to implement the Google Developer Documentation Style Guide, but that’s not enough if we want to up-skill the developers in an empathetic way. Additional tools that we have in place are a technical documentation user guide that includes a slim but complete technical writing 101, a 50-minute technical writing workshop available for any team that wants it, and a set of templates to help engineering teams get started. The workshop is a frontend to the user guide and gives us the opportunity to spend time with our users and get their feedback.
Make sure you have documentation feedback loops
This is my dream scenario. A platform team has a good quality documentation site up in Backstage. One of the team’s users is using this documentation to perform a task. While doing so, they spot a technical error in the documentation. The instructions are incorrect. The user understands that feedback is important and either submits a PR (Pull Request) to make the required change or uses the TechDocs Open new GitHub issue feature to raise a GitHub Issue.
The owning team gets the feedback and fixes (or schedules the fixing of) the documentation. When the update is made, the user is notified. The user feels a sense of satisfaction because their feedback was addressed and is encouraged to give feedback again.
This is the way to keep documentation fresh and continue to drive up the quality. Making sure we have doc feedback loops in place is an important part of our strategy.
Work to change the documentation culture
I read this quote somewhere recently:
At its core, an organisation’s culture is everyday behaviours, repeated, until they become the norm.
I like that and it applies to documentation culture. These are some of the behaviours that we are trying to change — all could be said to come under the rubric of knowledge reuse:
- Repetitive answering of user questions on chat channels → Quality documentation and answer with a link (thanks GitLab for that one)
- Immediate reaching out for support → Self-search, self-serve, and self-learn
- Blinkered approach to software engineering work → Look up and out and contribute knowledge that will help other and future colleagues; we call it paying it forward
What we are trying to do at Volvo Cars is lead by example and get others to buy into what we are trying to do. We are working to change everyday behaviours around documentation until they become the norm. Then we can say we have changed documentation culture. It’s the only way — it’s clear that a few technical writers can lead the way, but we can’t do it on our own.
What’s next?
We’ve been at this game for two years now and we have made great progress. But there is still so much to do. We see opportunities in utilising the Backstage API (Application Programming Interface) for checks and automation. And then there is how can we use AI (Artificial Intelligence) to super-charge our mission? We also need to get our metrics in shape. How many documentation updates are being made? How many feedback loop events?
Most would agree that quality internal technical documentation is a key component of a great developer experience. If you are doubtful, just stop and imagine the opposite. But then the conversation moves to: Yes, but how can we achieve that? We are on that journey here at Volvo Cars. The hope is that this blog post gives you some insights, inspiration, and concrete initiatives to apply to your own documentation journey.
What about your company? How are you tackling challenges around internal technical documentation? Feel free to respond here on Medium and tell us of your experience. We are curious ones.
