Standard Readme

Readme Standard Style

This repo is for standardizing how READMEs should look. The goal is to have a spec, a linter, a generator, a badge, and examples. This document is also an example of a standard README.

Table of Contents

• Background
  • Goals
• Installation
• Usage
  • Generator
  • Badge
  • Example Readmes
• Contribute
• License

Background

Standard Readme started with in the issue originally posed by @maxogden over at feross/standard in this issue. 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. This is 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.

~ Ken Williams, Perl Hackers

Goals

1. 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.
2. An example README. This Readme is fully standard-readme compliant, and there are more examples in the example-readmes folder.
3. A linter that can be used to look at errors in a given Readme. Please refer to the tracking issue.
4. A generator that can be used to quickly scaffold out new READMEs. See generator-standard-readme.
5. 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 i -g standard-readme

Usage

Currently, this is only a README spec.

$ standard-readme
// Will print spec.md to the console

Generator

To use the generator, look at generator-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:

[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

Example Readmes

To see how the specification has been applied, see the example-readmes.

Contribute

Feel free to dive in! Open an issue or submit PRs.

Standard Readme follows the Contributor Covenant Code of Conduct.

License

MIT (c) Protocol Labs