Documentation Best Practices

Astasia Myers
Apr 6 · 5 min read

Last Wednesday, I hosted Pavi Sandhu to discuss the importance of building and maintaining good developer documentation. Pavi has more than 20 years of experience leading documentation and user education initiatives at companies such as Salesforce, Amazon, Mesosphere, and MongoDB. Pavi co-founded Salesforce’s learning platform, Trailhead, which now has more than two million users. Below we will discuss some key takeaways from the discussion.

Technical marketing vs. documentation. Technical marketing focuses on informational content like data sheets and white papers that are used to encourage product adoption. Documentation comes into play after someone decides to use the solution. It helps them learn how to use the product as quickly, easily, and efficiently as possible. The line can be blurry as good documentation can be part of the selling process because customers understand that they’ll be well-supported and have all the resources they need to use the product once they adopt it.

Content creation should be centralized. Often teams create documentation and technical content on different teams in an uncoordinated fashion. This can lead to duplicity and customer confusion because the same material is presented in different ways. By centralizing content creation you can make content development more cost effective and the common body of content can be assembled and shared with different audiences based on their needs.

There are five C’s of good documentation. Documentation should be correct, clear, complete, consistent, and customer-centric. You can evaluate any documentation or educational content by those standards and these factors can also then be a rubric for improving them.

Personas are important. Throughout the discussion Pavi emphasized that it is important when writing documentation to consider the different personas who may read it and develop content specifically around them. There could be different personas as part of the pre-sales process like the business decision maker, the CTO, and engineering managers. Post-sales personas tend to be engineers, engineering managers, and end users.

Writers should understand the customer journey of using the product by persona and then develop content that assists the customer in that journey. The role of great customer docs is to actually move customers across this journey as quickly and efficiently as possible. The technical sophistication of the persona affects how quickly they move through the adoption journey. Identify each persona, what they need to learn, and write documentation that maps their path.

Think of documentation as education. Define learning objectives which are simple statements that identify what the customer will be able to learn or do after they’ve gone through a particular set of documentation. Learning objectives provides a focus for defining the content and frames customer journeys as milestones. Documentation should be framed as helping users crawl, walk, run, and fly, which is advocacy.

Think about documentation as an educational course that has sequenced content. Each module should have concepts, tasks, and reference material. It should explain a concept, then it goes through the steps of doing a particular task, and then leaves the reader with reference information for further exploration. The relative portion of concept, task, and reference material will vary based on the stage of the readers’ understanding. For example, advanced user documentation may have a smaller portion of concept defining and a higher portion of task and reference material. When the user has completed the materials they should have gone from ignorance to mastery. Ideally, if someone has gone through the content, there should be a way to assess that they’ve learned it by doing a simple quiz or having them go through maybe a test exercise.

Framing documentation as educational content helps developer relations. It builds trust with the end user and presents an opportunity to be a thought leader for not just your offering but the broader space and vision of the future.

Docs should tell a story. Stories take readers from point A to point Z in a very structured, specific way such that steps have been organized for the specific customer persona. If you don’t take this approach docs can end up being feature-centric. In other words, when a new feature is built documentation simply showcases how it works. But customers don’t buy features. They buy benefits. They buy solutions.

Engineers should be involved in documentation writing. Engineers often reflect the end user and can best speak to how the tool works and fits into the readers’ workflow. Teams should create incentive programs to encourage developers to be involved in documentation. For example, set up a program where they have templates, editing support, and recognition for creating content.

10:1 is the optimal ratio of developers to technical writers. Pavi suggested one technical writer can typically support two scrum teams. When you have about 10 engineers it is useful to have a technical writer, suggesting that early stage companies should have a contract or full-time technical writer. As the team scales, it is useful to bring technical writers in house. Usually a 50 person company should have someone in house working on documentation.

A trend is authoring documentation in markdown. Authoring docs in markdown and saving them as plain text files in GitHub is becoming the norm. It’s a good practice because it makes it easier for people to collaboratively edit and upgrade the docs overtime. Engineers can contribute to it by responding to pull requests and providing feed all in Git.

Tracking documentation website traffic is a useful KPI. Tracking website traffic gives teams some sense of the relative level of interest and attention to the documentation overall and specific pages. Tracking analytics can be really valuable because you can find out if visitors are beginners, intermediate, or advanced so you can better understand the customer.

Documentation is part of the product. The planning, preparation, and creation of docs need to occur hand-in-hand as the product is being developed. Writers should be embedded with engineers as part of the agile process and scrum team. Docs highlight flaws and deficiencies in the product design. If a product needs a lot of documentation, chances are it’s not that well designed. It’s not that user centric. Documentation sheds light on product quality and usability. It can be a strategic asset that can give your product a competitive advantage.

Memory Leak

Redpoint perspectives on distributed computing…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store