Your step-by-step guide to more effective documentation

The Open Organization Ambassadors recently released the Open Organization Maturity Model, a framework for organizations can use to "level up" on five characteristics: transparency, inclusivity, adaptability, collaboration, and community. Inspired by the effort that my fellow ambassadors and I invested to produce that valuable tool, I recently applied the maturity model concept to README development. You can find the README maturity model here, as part of my Feedmereadme project/crusade to improve the world's READMEs.

Creating a maturity model based on the production of a single file might seem like overkill at first. But given the importance of the README as the entry point for most open source projects, and the aversion many developers harbor toward writing documentation, providing an on-ramp and structure for this critical project element seems not just practical but critical.

What's more, because open organizations often rely on copious (and effective) documentation to accomplish their work with transparency and accountability, an ability to review, revise, reassess documentation is extremely valuable. The README maturity model aims to help your teams develop it by giving you a framework to evaluate documentation at five distinct "levels" of development.

Let me explain them.

Level One: "The Code is the Documentation"

In the echo chamber that is my Twitter feed, no one agrees that "the code is enough documentation." Thought leaders like Kelsey Hightower of Google and Viktor Klang at Lightbend praise the work of technical writers who turn code into decipherable stories. Nevertheless, too many people still expect the code to be the best documentation developers are willing or able to provide.

This expectation recently arose during an exchange I had with a product colleague who recommended that, in planning an upcoming bug bash with my team, I withhold all mention of documentation fixes lest the crowd become frightened and avoid participating. "If we assume devs will hate writing docs, then they will come to assume in response that they should hate writing docs," I said. Then I pointed to my teammate "Bob" and explained to the product specialist that, earlier this year, Bob asked in an agitated manner why we needed to write any internal READMEs on our repos because they amounted to "marketing bullshit." After working in an agile context for nearly a year and being regularly on-call, I noted, Bob recently suggested creating an Elasticsearch plugin using—what?!—README-driven development. The product specialist seemed pleasantly surprised by this transformation story.

And our bug bash produced three documentation-related suggestions for improvement.

But let's address the developer who absolutely hates writing docs. Whether it's because of writer's block, ambivalence, or not knowing what to say, the Maturity Model addresses these and other sources of README-related angst by starting at zero (or near-zero). Level One projects reflect the following:

• No/almost no README text of any sort
• No installation, configuration, running details
• No developer documentation
• No complimentary files, such as contributor guidelines
• No build status information, so there's no insight into the project's current state
• No suggested average response time to issues and/or pull requests
• No badges showing code coverage or other quality metrics
• What text is available may be obsolete or non-priority

Level One is fine for a personal project or experiment. For a company-hosted project, however, it poses some reputation risks. You might be signalling to prospective collaborators and recruits that your team doesn't value documentation.

Level Two: Bare-Minimum README

So, you want to provide a bit more documentation than a bare skeleton or total void. Good! The Maturity Model considers the following ingredients for baking a bare-minimum, Level Two README:

• Limited information about the project's functionality and purpose
• Basic installation, configuration, running details for users, possibly untested and incomplete
• Basic or no developer documentation
• A line in the README about contributions, but no dedicated file
• A line about the project's build status, though it may be obsolete; or no build status information
• A line about the average response time to issues and/or pull requests
• No badges showing code coverage or other quality metrics
• The text is infrequently updated and may be obsolete or inaccurate

After reading the above bulleted list, you might wonder how much value such a README offers to the prospective user or contributor. The answer: Not much. I suggest skipping right to Level Three. That's where we get serious.

Level Three: Basic README

Here's where your README begins to speak for you and your work—answering critical questions and providing essential context about the project's purpose and utility. It's the level that enables you to begin a meaningful dialogue with the broader community. A Level Three README offers:

• Some detailed information about the project's functionality, usefulness and purpose
• Basic installation, configuration, running details for users, tested and complete
• Basic documentation for potential contributors
• A vision statement or project roadmap for onboarding new contributors
• A Contributing.md/.rst file with basic information
• A line about the project's build status, but minimal: "under development" or "stable"
• A line about the average response time to issues and/or pull requests
• At least one badge showing code coverage or other quality metrics
• Text updated at monthly or quarterly intervals, so inaccuracies may exist

Most submissions to Feedmereadmes come with READMEs situated between this level and the previous one. Often the README is outdated or incomplete; it comes with user instructions but no guidance for developers (or vice versa). Contributor guidelines are basic, but possibly so minimal as to present friction that more detailed style notes or user-tested steps would avoid.

What's most frequently missing from these projects—i.e., "I could automate/botify myself to ask these questions to all applicants"—are answers to questions about project purpose: why the project exists and how it's similar to or different from existing solutions. Has it actually produced any results proving its merit? Answers to those questions take us to the next level.

Level Four: README with purpose

If you really want to build community, and entice big companies to consider participating in it, presenting your project as a viable product can make all the difference. It doesn't have to be slick or come with a commercial, but ensuring that your Level Four README includes the following helps:

• Detailed information about the project's purpose, functionality and special features/attributes
• Detailed user installation, configuration, and running instructions that may or may not be recently updated; information about common errors and how to resolve them
• Detailed documentation for potential contributors
• A detailed vision statement or project roadmap for onboarding new contributors
• A Contributing.md/.rst file with detailed style guidelines
• The build status identifies specific aspects of the project that are incomplete and/or causing instability
• Clear information about the average response time to issues and/or pull requests
• One or more badges showing code coverage or other quality metrics
• Text updated at monthly or quarterly intervals, so inaccuracies may exist

At this level, you're regularly making documentation changes and managing expectations around response time and support. You've covered both developer and user instructions, and have tested them to ensure they're comprehensible. You've also anticipated where your users and contributors might go astray, and helped them overcome roadblocks. Finally, you've set yourself up for the final level in our five-step journey to README greatness.

Level Five: Product-oriented README

Here is where you need to be careful balancing "marketing bullshit" with valuable information. Your top-notch, Level Five README includes these elements:

• Detailed information about the project's purpose, functionality and special features/attributes, so that the reader can immediately understand the usefulness and impact of its features and attributes
• Includes user testimonials and evidence of past performance in real development situations
• Detailed user installation, configuration, and running instructions, tested and current; information about common errors and how to resolve them
• Detailed documentation for potential contributors
• A detailed vision statement or project roadmap for onboarding new contributors
• Embedded visual aids like diagrams and demos
• A Contributing.md/.rst file with detailed style guidelines
• The build status identifies specific project aspects that are incomplete and/or causing instability
• Clear information about the average response time to issues and/or pull requests
• One or more badges showing code coverage or other quality metrics
• Text updated at weekly or even daily intervals, so inaccuracies are unlikely

These READMEs leverage visuals and user feedback to reinforce that their parent projects solve technical solutions effectively. Visuals in particular go a long way in showing a project in action. Two of our most successful projects, SwiftMonkey and Fashion-MNIST, leveraged visualizations and animations upon initial publication—making them accessible to both developers and non-developers. Continuous documentation improvement and detailed information address questions at the outset, reducing friction for both users and contributors.

The README Maturity Model is not a concrete rulebook; boundaries between levels are fluid. They might also offer room for improvement, which is why the model is open source and open to contributions. One lesson I've learned through creating and editing documentation is that there's always room for improvement. Hopefully the model provides you with a framework for measuring your improvement as you go.