Skip to content

Latest commit

 

History

History
68 lines (57 loc) · 5.09 KB

README-maturity-model.md

File metadata and controls

68 lines (57 loc) · 5.09 KB
Raw

README Maturity Model

This isn't scientific, but meant to offer a little guidance.

Level One: "The Code is the Documentation"

  • No/almost no README text of any sort.
  • No installation, configuration, running details.
  • No developer documentation.
  • No complementary 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.

Recommendation: Sometimes developers post personal projects and experiments that aren't ready-to-share. In these cases, having little to no documentation may be acceptable. We recommend that the README indicates the nature/status of the project. For example, warn users that "this project is experimental/personal, so use at your own risk."

Level Two: Bare-Minimum README

  • Limited information about the project's functionality and purpose.
  • Basic installation, configuration, running details for users, but 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.

Recommendation: A Level Two README aims for a broad audience, but its incompleteness causes frustration and wasted effort. Sometimes this is worse than having no documentation at all. Include a note stating whether the project is early-stage, unstable, experimental or personal.

Level Three: Basic README

  • 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.

Recommendation: A Level Three README is thorough enough to support small-scale community growth. Early-stage projects requiring contributor development should aim to reach this level before publication. Widespread project adoption can happen, although the README might pose barriers.

Level Four: README with purpose

  • 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.

Recommendation: A Level Four README can support large-scale community usage and growth. It might lack some ingredients necessary for achieving widespread use and adoption. Corporations that impose stringent standards for adoption might hesitate before using it.

Level Five: Product-oriented README

  • 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.
  • 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.

Recommendation: Level Five READMEs usually emerge from projects with broad contributor/user bases. Their detail reinforces production-ready use and supervised contributions. Every project should aspire to this level of documentation.