Category: Technical Documentation
Last updated on Jul 28, 2020
In a perfect world, everyone in the company would jump at the chance to write documentation. If you’re a technical writer, you probably think writing is fun – but there may be others out there who would liken the writing process to having a tooth drilled.
Perhaps you have dedicated technical writers for your product documentation and tools, and you don’t need anyone else to help. For most teams, this won’t be the case – not least because you’re likely to need engineers to contribute technical information.
As a software development company, you know the value of product documentation and how it’s essential to your Minimum Viable Product. So how can you persuade developers to spend more time writing documentation?
First and foremost, it is not the primary job of developers to write documentation. Their job is to write code – a very different type of writing. You should make sure you really need them to write docs, in case their time could better be spent on other tasks. Don’t just ask developers to write docs because of poor process.
Even if they enjoy writing, developers operate under the engineer mindset. They want to build software, rather than write about it. You need to show them the utility of what you are asking them to do, before you can convince them to spend valuable time on it. And that’s not easy.
But what about those developers who already understand the value of documentation, but just don’t want to write it themselves? Developers are typically under a lot of pressure to deliver working software, and may genuinely not have time to write documentation. The value of “writing the docs” needs to be built into the overall culture of the team.
It may be somewhat easier to convince developers to write developer documentation, since it’s easier to imagine themselves as the audience. The main beneficiary of product documentation is the customer, who wants to find out more about the product and how it works. Introducing easy to use documentation tools and implementing documentation as a culture in the company will motivate developers to contribute to technical documentation
One way to convince more developers to contribute to documentation is using the docs like code methodology, outlined by Anne Gentle. “Docs like code” involves a few different practices, but the main one is “treating documentation as artfully and mindfully as you would the code”.
Docs like code means doing things like:
You may not actually need your developers to write the documentation. It might be the case that you’re perfectly capable of producing all the documentation you need within the technical writing team – but that’s not the end of the story.
You may instead want your developers to verify the technical accuracy and completeness of what you have written. For example, you want to check that the procedures you have written actually work.
But the technical review can be an even more painful process than simply getting an SME to do a brain dump in the first place.
Splunk has some more advice to offer on this front:
Emphasise to your developers that incorrect documentation is much worse than having none at all. Open up the feedback loop between developers and customers, and show them how customers are reacting to the documentation. Let them know when customers have really appreciated the documentation, or been helped by something they’ve written.
As we mentioned earlier, sometimes using the same tools as the developers can be the route to getting them to write the documentation. When you use a tool like GitHub that makes use of pull requests, code reviews can also include documentation reviews in the same way.
Sometimes, you might want to write documentation in your own system, like our own knowledge base software Document360.
Document360 has a powerful in-built versioning process that lets you document different product releases at the same time. Contributors to your documentation can write in Markdown, a format that is often familiar to developers.
Whichever tool you use, building strong relationships with your developers is crucial if you want them to write documentation.