Some companies have great documentation and some not so much. If you’re wondering what it takes to go from zero to world class documentation, check out this documentation maturity model. This model is for public facing documentation for APIs.

It covers every stage of documentation development with a focus on what kind of content you will have available.

And if you don’t like the stage you’re at, remember that creating great developer content is a journey. Every company with great documentation went through all these phases at some point.

If you’re looking for how to create metrics for your documentation try How Do You Know Your Developer Documentation is Successful? - Metrics!

0 — No Docs at All!

You don’t have public facing documentation in the form of a documentation portal or area of your website where customers can read about your product. You may have:

• Internal documentation that people use to learn your product when they onboard.
• Documentation engineers create for their projects.
• Customer support notes / early stages Knowledge Base.
• Marketing content that covers some questions but is not focused on technical details.

Process

Regarding process, you don’t have any processes in place for creating or maintaining documentation.

If customers request documentation, it’s likely provided in individual files put together in response to the request.

1 — Docs? At Least We Have Something

You have a little bit of customer facing documentation, either in a portal or area of your website. The documentation covers basics like full descriptions for all your API endpoints, but they may be inaccurate or incomplete.

It may include guides, tutorials, or other how-to content, but it’s inconsistent and some key information is still missing. You may have:

• A hodge podge of code samples where the language changes from document to document without consistently choosing a few languages to present for each of your basic guides/tutorials/how-tos.
• Content covering key processes at the conceptual level without presenting code samples.
• Scattered, incomplete content that would be helpful if better organized or completed.
• Tools that are helpful for users, but they may be incomplete, broken, or working but not showcased effectively.
• No branding, no SEO, no metrics.

Process

Content is likely created as a knee jerk reaction to a question or issue, or when someone has free time. Documentation may go through a review, but there is no standard style or review cycle in place.

If customers request documentation, it’s likely that they are pointed to where your documentation lives, and then they come back with tons of questions. While support or other employees may be able to answer these questions, leaving documentation at this phase will cause a pain point when you start to scale as a company.

You may see increased support times, loss of new customers who want easy-to-use docs, and increased time spent troubleshooting or building for customers when customers could be building for themselves.

2 — We’ve Got the Basics Covered

You have selected a documentation strategy and budget. You’ve built a documentation portal or integrated docs into your marketing website. You may have:

• The start of a developer forum.
• Consistent use of at least one or two languages for code samples.
• Complete reference documentation for your API endpoints.
• Key concepts for your API demonstrated with code samples.
• Helpful tools like SDKs or similar, with the language matching your code samples.
• Content covering more complex use cases with your API.
• A few sample apps.
• A little bit of blogging for developers, but no strategy in place for content.
• Some use of SEO strategy. (This can be a slippery slope for technical documentation. SEO strategy for documentation will be discussed in a future article.)
• Some branding, you might have metrics.

Process

You likely have one or more technical writers or developer advocates who handle documentation as part of their role. Content is created using an agreed upon style and a process that includes a review cycle. The process may not be fully standardized.

If customers request documentation, they are pointed to your online documentation.

They are likely to come back with common troubleshooting questions the documentation doesn’t yet address, issues to do with their specific implementation or advanced topics not covered in the documentation, and questions about complementary tools that would help them complete tasks with your API.

3 — Great Documentation

You have a documentation portal or integrated docs on your marketing website. You cover all the endpoints accurately, all the basic concepts with code samples for everything in at least two languages, you have sample apps and you may have:

• Code samples and content contributed by developers outside the company.
• Lots of sample apps demonstrating multiple use cases.
• Helpful tools like SDKs, command lines, or API explorers are functional and in a centralized, easy to access location.
• Troubleshooting documentation for key issues that occur regularly in support.
• Documentation about complementary tools that make it easier for developers to complete tasks with your API.
• Some use of SEO strategy. (This can be a slippery slope for technical documentation. SEO strategy for documentation will be discussed in a future article.)
• A presence in places with developer focused content like Stack Overflow, GitHub, Glitch, etc.
• A strategy for creating blogs for developers and developer forum posts.
• Everything is branded to make it clear it’s from your company.
• A way to collect metrics and basics for how to interpret the metrics.

Process

You have technical writers or developer advocates. Content has a fully standardized process for how it will be created and reviewed. You are developing or building processes for content that’s to do with blogging and forum posts. You are starting to develop a way to review metrics.

If customers request documentation, they can probably answer most of their questions using the content you have available (though they may want to talk to a person instead, but that’s a separate issue).

4 — World Class Documentation

World class documentation is everything you’ve read about so far, but just a little bit more. Part of becoming world class is brand recognition, so take that into account when making an assessment. World class documentation has:

• A custom built documentation portal that addresses any needs of technical writers as well as customers. (The reason is you will get better SEO results than with an out-of-the-box solution, though that will cost a lot less to build and maintain.)
• A complete knowledge base.
• An active developer forum where developers are helping each other with answers to questions.
• Detailed, extensive content covering API reference, tutorials, guides, troubleshooting, and advanced concepts.
• Detailed, extensive content about complementary tools for working with your API.
• Code samples for all core content in at least the 3 most popular languages for your API, but it’s likely you offer 5 or 6 different choices.
• Many content sources — developers can easily read content geared towards them in a knowledge base, forum, popular site like Stack Overflow, or your documentation portal.
• A strategy for creating blogs for developers and developer forum posts.
• Written content is offered in more than one language based on what languages are most popular with your customers.
• Everything is branded to make it clear it’s from your company.
• You have great SEO strategy.
• A detailed, established way to collect and interpret metrics that’s agreed upon by key stakeholders.

Process

You have a team of writers focused on different aspects of your content. You have documented all the processes you use to create content. You regularly schedule and create useful content for blogs, your forum, and your documentation site. You have clear ways to measure success using metrics, and you’ve documented the way your metrics are used and included them in documentation goals and strategy planning.

If customers request documentation, they can probably answer most of their questions using the content you have available (though they may want to talk to a person instead, but that’s a separate issue).

5 — It’s Doc Maintenance Time

In this model, reaching five is not necessarily the best. I’d argue that achieving three or four depending on your company’s business needs is best. Five means that you have so much content and so many tools that it’s time to address some issues like:

• Retiring content that is out of date.
• Updating content as needed to match any product changes.
• Updating or retiring developer tools for your API.
• Reviewing your metrics for ways to improve.
• Reviewing your SEO strategy.

Process

Create processes for handling updating or retiring documentation and tools. Make any required revisions and then periodically use these procedures so your documentation stays at either a three or a four.

And in Conclusion…

This model is to help you assess where you are at and what you need to do to improve documentation.

You may find that you have items from the different phases. If this is the case, assess by figuring out which phase your documentation matches with the most, and then count the items from other phases as being ahead of the game.

This article was originally published by Erikka Innes on medium.