saturneric/standard-readme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fill out story!

Browse Source
This commit is contained in:
Richard Littauer 2016-07-27 11:49:39 -04:00
parent 1bb0e8ea88
commit 38c80ab16c
1 changed files with 17 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@ -7,12 +7,20 @@
> 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.
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:
1. The specification for how a standard README should look.
2. A link to a linter you can use to keep your README maintained.
3. A link to a generator you can use to create standard READMEs.
4. A badge to point to this spec.
5. Examples of standard READMEs - such as this one.
## Table of Contents
- [Background](#background)
- [Goals](#goals)
- [Installation](#installation)
- [Usage](#usage)
- [Generator](#generator)
@ -23,7 +31,7 @@ This repo is for standardizing how READMEs should look. The goal is to have a sp
## 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.
Standard Readme started with 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), about whether or not a tool to standardize readmes would be useful. 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 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
@ -35,7 +43,12 @@ change the module's internals as long as the interface remains the same.
~ [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document)
### Goals
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 worry about whether or not your initial documentation is good, and spend more time writing and using code.
As well, standardizing can help elsewhere. 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:
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).