Permalink
Switch branches/tags
Nothing to show
Find file
2d05db9 Oct 28, 2017
@LappleApple @pbh101 @getconor @remotesynth
72 lines (60 sloc) 5.37 KB

Up for Discussion:

  • This is a draft, spun up in about 20 minutes (July 14, 2017). Please feel free to suggest anything.
  • Apache's maturity model might offer a more appropriate format. Feel free to open an issue if you'd like to start the discussion on this.

README Maturity Model

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.