91 lines
4.1 KiB
Markdown
91 lines
4.1 KiB
Markdown
# Standard Readme
|
|
|
|
[](http://ipn.io)
|
|
[](http://ipfs.io/)
|
|
[](http://webchat.freenode.net/?channels=%23ipfs)
|
|
[](https://github.com/RichardLitt/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](#background)
|
|
- [Goals](#goals)
|
|
- [Installation](#installation)
|
|
- [Usage](#usage)
|
|
- [Generator](#generator)
|
|
- [Badge](#badge)
|
|
- [Example Readmes](#example-readmes)
|
|
- [Contribute](#contribute)
|
|
- [License](#license)
|
|
|
|
## Background
|
|
|
|
Standard Readme started with in the issue originally posed by [@maxogden](https://github.com/maxogden) over at [feross/standard](https://github.com/feross/standard) in [this issue](https://github.com/feross/standard/issues/141). A lot of that discussion ended up in [zcei's standard-readme](https://github.com/zcei/standard-readme/issues/1) repository. While working on maintaining the [IPFS](https://github.com/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](http://mathforum.org/ken/perl_modules.html#document)
|
|
|
|
### Goals
|
|
1. A well defined **specification**. This can be found in the [Spec document](spec.md). 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](https://github.com/RichardLitt/standard-readme/issues/5).
|
|
4. A **generator** that can be used to quickly scaffold out new READMEs. See [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme).
|
|
5. A **compliant badge** for users. See [the badge](#badge).
|
|
|
|
## 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.
|
|
|
|
```sh
|
|
$ 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](https://github.com/RichardLitt/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**.
|
|
|
|
[](https://github.com/RichardLitt/standard-readme)
|
|
|
|
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](example-readmes/).
|
|
|
|
## Contribute
|
|
|
|
Feel free to dive in! [Open an issue](https://github.com/RichardLitt/standard-readme/issues/new) or submit PRs.
|
|
|
|
Standard Readme follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) Code of Conduct.
|
|
|
|
## License
|
|
|
|
MIT (c) Protocol Labs
|