Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.

Documentoring: Growing a “Love the Docs” Community

by David Oliver

Documentoring is a possibly made up word that defines how David approaches doing his job. It is about getting everyone you work with invested in quality products and quality docs.

During his career he has seen the ratio writers to engineers go from 1 writer to 10 engineers (and related fields) to 1 writer to 50 engineers. This has happened because of a lot of factors, including:

• Financials
• He is more experienced and can do more
• Industry changes from waterfall to agile
• The change in the amount of collaboration between writers and engineers

His role has also changed with a shifting the balance between “create” and “curate”. The volume of writing is now much lower as more content comes in from other sources. This means he is spending more time looking at things like automated builds, testing the docs, and single sourcing.

Being an effective curator can be more valuable than being a prolific creator.

This led him to the realization that the most effective person to write software documentation is usually the software engineer. The turnabout is that they are also the least appropriate person too write software documentation because they have other objectives and skill sets. This led to him wanting to convert the “you know all about this because you built it, tell me everything I need to know” conversation into a hand-off.

Documentation is Product.

If you don’t have documentation you don’t have a product. As an example, he shared two stories. The first was of a great product with flawed docs. It was a cloud service that was to be deployed with a bunch of other services. They had a great product that met a lot of challenges but the docs were not cared for. These observations followed:

• There was lots of early interest.
• Installation and configuration was difficult.
• All of the user feedback was negative and revolved around difficulty of use.
• A large portion of the features were not used as users didn’t get that far.
• Ultimately a lot of users were lost.

Story two was of the same product but in a local implementation. It was a flawed product with great docs. The flaws were because they were forcing a cloud product into a limited non-cloud format. The feedback was very different.

• Installation and Configuration was easy.
• User feedback concentrated on product improvements.
• All product features were utilized by early users.
• There was now runway for improvement alongside a responsive user base.

Give yourself the best chance to succeed

Use the kinds of products the engineers use. As they began using GitHub, Sphinx, different markups that weren’t XML, JIRA, etc., he made changes. This meant the writers could easily integrate with the engineering team, often early on in the development cycle.

He also began practicing Documentoring. A method of encouraging quality engineering documentation contribution.

The Documentoring Toolbox

• Persistence - It is aggressive
• Process - Sharing JIRA with flagging has worked well
• Events - Hold workshops to build a bridge between the islands of docs and engineering. He held a “paper jam” (amnesty) on the docs
• Tantrums - Storming out of or into meetings and throwing things
• Bribes - Doughnuts tend to work

Bringing these to bear has caused his team to realize the value of documentation and how they can have a direct impact on quality.

The most effective tool, however, has been empathy. Empathy with the user and the engineer. This is the best way to figure out what is needed and the best way to get the information.