Top Related Projects
A curated list of awesome READMEs
An awesome README template to jumpstart your projects!
📄 CLI that generates beautiful README.md files
README.md template for your open-source project
:love_letter: Things I've learned about writing good READMEs.
Quick Overview
Standard Readme is a specification for README files, providing a standard format and guidelines for creating clear and comprehensive project documentation. It aims to improve the consistency and quality of README files across open-source projects, making it easier for developers to understand and contribute to various repositories.
Pros
- Provides a clear structure for README files, ensuring important information is included
- Improves project discoverability and understanding for potential users and contributors
- Offers flexibility with optional sections to adapt to different project needs
- Includes a generator tool to easily create compliant README files
Cons
- May feel restrictive for projects with unique documentation needs
- Requires effort to convert existing README files to the standard format
- Some developers may prefer more freedom in structuring their documentation
- The specification may not cover all possible scenarios or project types
Getting Started
To create a Standard Readme compliant README for your project:
- Visit the Standard Readme repository
- Copy the
standard-readme.mdtemplate from the repository - Paste the template into your project's README.md file
- Fill in the sections with your project's information
- Remove any unnecessary optional sections
Alternatively, you can use the Standard Readme generator:
npm install --global standard-readme-spec
standard-readme
This will guide you through creating a compliant README file interactively.
Competitor Comparisons
A curated list of awesome READMEs
Pros of awesome-readme
- Provides a curated list of exemplary README examples, offering inspiration and best practices
- Includes a wider variety of README styles and formats, catering to different project types
- Offers a community-driven approach with contributions from various developers
Cons of awesome-readme
- Lacks a standardized structure or template for creating READMEs
- May overwhelm users with too many options, making it difficult to choose the best approach
- Does not provide detailed guidelines on how to write specific sections of a README
Code comparison
While both repositories focus on README files, they don't contain directly comparable code snippets. However, here's an example of how they differ in their approach:
standard-readme:
# Project Name
Short description of the project.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
awesome-readme:
# Awesome README [](https://github.com/sindresorhus/awesome)
A curated list of awesome READMEs
## Examples
- [ai/size-limit](https://github.com/ai/size-limit#readme) - Project logo, clear description, screenshot, step-by-step installing instructions.
- [aimeos/aimeos-typo3](https://github.com/aimeos/aimeos-typo3#readme) - Project logo. Clear description of what the project does. Demo screenshot. TOC for easy navigation.
An awesome README template to jumpstart your projects!
Pros of Best-README-Template
- Visually appealing with a modern design and badges
- Includes a live demo link and screenshot section
- Provides a more comprehensive structure for larger projects
Cons of Best-README-Template
- May be overly complex for simple projects
- Less focus on standardization across different repositories
- Requires more customization to fit specific project needs
Code Comparison
Best-README-Template:
<!-- PROJECT LOGO -->
<br />
<div align="center">
<a href="https://github.com/othneildrew/Best-README-Template">
<img src="images/logo.png" alt="Logo" width="80" height="80">
</a>
standard-readme:
# Project Name
[](https://github.com/RichardLitt/standard-readme)
One Paragraph of project description goes here
The Best-README-Template focuses on visual appeal with a centered logo and more elaborate structure, while standard-readme emphasizes simplicity and standardization with a concise header and compliance badge.
📄 CLI that generates beautiful README.md files
Pros of readme-md-generator
- Interactive CLI tool for generating READMEs, making the process more user-friendly
- Automatically fetches project information from package.json and git config
- Supports multiple languages and includes badges for various services
Cons of readme-md-generator
- Less flexible than standard-readme for customizing content structure
- May generate unnecessary sections for simple projects
- Requires Node.js to run, unlike standard-readme which is language-agnostic
Code Comparison
standard-readme template:
# Project Name
One Paragraph of project description goes here
## Install
```bash
npm install
readme-md-generator output:
# Welcome to project-name 👋
[]()
[]()
> Project description
## Install
```bash
npm install
The code comparison shows that readme-md-generator automatically includes version and documentation badges, while standard-readme provides a simpler starting point for customization. Both tools offer similar installation instructions, but readme-md-generator's output includes more pre-generated content and formatting.
README.md template for your open-source project
Pros of readme-template
- More visually appealing with badges and images
- Includes a section for project logo
- Provides a clear installation guide with code snippets
Cons of readme-template
- Less comprehensive than standard-readme
- Lacks specific sections for security and API documentation
- Does not provide guidelines for maintaining consistency across projects
Code Comparison
standard-readme:
## Install
This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed.
```bash
$ npm install --global standard-readme-spec
readme-template:
```markdown
## Installation
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.
```bash
pip install foobar
The standard-readme template provides a more detailed explanation of prerequisites, while the readme-template offers a simpler, more concise installation guide. standard-readme uses npm as an example, whereas readme-template uses pip, reflecting different target audiences.
Both templates serve their purposes well, with standard-readme focusing on comprehensiveness and consistency, and readme-template prioritizing visual appeal and simplicity. The choice between them depends on the project's needs and the developer's preferences.
:love_letter: Things I've learned about writing good READMEs.
Pros of art-of-readme
- More comprehensive guide on writing effective READMEs
- Includes real-world examples and case studies
- Offers in-depth explanations of README components and their importance
Cons of art-of-readme
- Less structured approach compared to standard-readme
- May be overwhelming for beginners due to its extensive content
- Lacks a standardized template for quick implementation
Code comparison
standard-readme provides a basic template:
# Project Name
Short description
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
art-of-readme doesn't provide a specific template but offers guidelines:
# Project Name
One-paragraph explanation of what your project does.
## Features
- Key feature 1
- Key feature 2
- ...
## Installation
Describe how to install your project.
## Usage
Show how to use your project with examples.
While standard-readme focuses on providing a consistent structure, art-of-readme emphasizes the importance of crafting engaging and informative content. standard-readme is more suitable for projects requiring a standardized approach, while art-of-readme is better for those seeking to create more customized and comprehensive documentation.
Convert 
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Standard Readme
A standard style for README files
Your README file is normally the first entry point to your code. It should tell people why they should use your module, how they can install it, and how they can use it. Standardizing how you write your README makes creating and maintaining your READMEs easier. Great documentation takes work!
This repository contains:
- The specification for how a standard README should look.
- A link to a linter you can use to keep your README maintained (work in progress).
- A link to a generator you can use to create standard READMEs.
- A badge to point to this spec.
- Examples of standard READMEs - such as this file you are reading.
Standard Readme is designed for open source libraries. Although itâs historically made for Node and npm projects, it also applies to libraries in other languages and package managers.
Table of Contents
Background
Standard Readme started with the issue originally posed by @maxogden over at feross/standard in this issue, about whether or not a tool to standardize readmes would be useful. A lot of that discussion ended up in zcei's standard-readme repository. While working on maintaining the IPFS repositories, I needed a way to standardize Readmes across that organization. This specification started as a result of that.
Your documentation is complete when someone can use your module without ever having to look at its code. This is very important. This makes it possible for you to separate your module's documented interface from its internal implementation (guts). This is good because it means that you are free to change the module's internals as long as the interface remains the same.
Remember: the documentation, not the code, defines what a module does.
Writing READMEs is way too hard, and keeping them maintained is difficult. By offloading this process - making writing easier, making editing easier, making it clear whether or not an edit is up to spec or not - you can spend less time worrying about whether or not your initial documentation is good, and spend more time writing and using code.
By having a standard, users can spend less time searching for the information they want. They can also build tools to gather search terms from descriptions, to automatically run example code, to check licensing, and so on.
The goals for this repository are:
- A well defined specification. This can be found in the Spec document. It is a constant work in progress; please open issues to discuss changes.
- An example README. This Readme is fully standard-readme compliant, and there are more examples in the
example-readmesfolder. - A linter that can be used to look at errors in a given Readme. Please refer to the tracking issue.
- A generator that can be used to quickly scaffold out new READMEs. See generator-standard-readme.
- A compliant badge for users. See the badge.
Install
This project uses node and npm. Go check them out if you don't have them locally installed.
$ npm install --global standard-readme-spec
Usage
This is only a documentation package. You can print out spec.md to your console:
$ standard-readme-spec
# Prints out the standard-readme spec
Generator
To use the generator, look at generator-standard-readme. There is a global executable to run the generator in that package, aliased as standard-readme.
Badge
If your README is compliant with Standard-Readme and you're on GitHub, it would be great if you could add the badge. This allows people to link back to this Spec, and helps adoption of the README. The badge is not required.
To add in Markdown format, use this code:
[](https://github.com/RichardLitt/standard-readme)
Example Readmes
To see how the specification has been applied, see the example-readmes.
Related Efforts
- Art of Readme - ð Learn the art of writing quality READMEs.
- open-source-template - A README template to encourage open-source contributions.
Maintainers
Contributing
Feel free to dive in! Open an issue or submit PRs.
Standard Readme follows the Contributor Covenant Code of Conduct.
Contributors
This project exists thanks to all the people who contribute.
License
MIT © Richard Littauer
Top Related Projects
A curated list of awesome READMEs
An awesome README template to jumpstart your projects!
📄 CLI that generates beautiful README.md files
README.md template for your open-source project
:love_letter: Things I've learned about writing good READMEs.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot