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.

What should you do about these reluctant writers?

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?

Are Developers Really So Different?

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 

Docs Like Code

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:

• Collaborating with contributors efficiently by keeping docs in the same system as the code
• Building documentation as consistently as possible across different platforms
• Applying software development tools and techniques to the documentation
  Using the principles of web development to style visually-appealing documentation sites
• Placing a high value on technical accuracy and consistency
• Trusting that your team members will appropriately value the documentation and place the needs of your end-users at the forefront of their work
• Automating and integrating documentation builds so you can focus on writing content
• Make sure you identify those subject matter experts who would be willing to become technical authors of the documentation. Do not make the mistake of over-editing their work, and explain why you are making certain changes. Always be willing to admit that there will be things that you don’t know.
  

  Advice From Splunk

  In their book The Product is Docs, Splunk offers a lot of advice for technical writers working with engineers on product teams, and how to get more involved with documentation.
  
  Here’s a shortlist of some of their rules:
• If you are a technical writer, learn the necessary skill and knowledge to be able to interact successfully with the engineers
• Work with your engineers in the same scrum teams, and include your documentation tasks in the same issue tracking software
• Understand the mental models that your engineers have and the language that they use
• Prepare beforehand for every substantial conversation that you have with an engineer
• Learn the relevant terminology of the engineer’s domain, whether that’s jargon or internal language
• Decide when to make a necessary compromise between strictly adhering to a style guide, and encouraging a willing SME to keep collaborating with the doc team
• Write your documentation in a wiki-based system to encourage contributions (naturally this approach won’t be suitable for everyone)
• Work flexibly with your SMEs so they don’t have to change their development practices to suit your workflows

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:

• Reviewing the technical validity of your documentation should be an ongoing process, not a one-time event
• Ask for reviews on the smallest chunks of documentation at a time, rather than asking for feedback for an entire manual
• When seeking a technical review, consider them as non-negotiable. They are an essential part of great documentation and require the participation of the entire product team
• Don’t wait until the draft review process to get feedback from your SMEs.
• Do spot reviews over email or Slack to get clarification over unclear concepts
• Prepare your material as much as you can, and make sure it is error-free, so as not to waste your reviewer’s time
• Make it clear what your priorities for the review are – if you want developers to focus on a single section of the documentation, let them know
• Take ultimate responsibility for the integrity of the review process, and ensure that everything you write undergoes technical review
• Choose the developers who worked on the feature you have documented as the technical reviewers
• Make yourself part of the development team by attending all develop meetings and reading all engineering documents
• Target your reviewers personally, and make sure none of your reviewers have to duplicate any work

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.

Final Remarks

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.