Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lappleapple/feedmereadmes

Free README editing+feedback to make your open source projects grow. See the README maturity model to help you keep going.
https://github.com/lappleapple/feedmereadmes

docs documentation feedback product-development project-manager readme readme-first user-friendly writer

Last synced: 18 days ago
JSON representation

Free README editing+feedback to make your open source projects grow. See the README maturity model to help you keep going.

Awesome Lists containing this project

README 

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