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

Add text from CPAN

Browse Source 
Closes #3
This commit is contained in:
Richard Littauer 2016-05-23 14:37:03 +02:00
parent bad0d305b9
commit f7acb59e51
1 changed files with 20 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@ -42,6 +42,16 @@ This repo is for standardizing how READMEs should look. The goal is to have:
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 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.
~ [Perl Hackers](http://mathforum.org/ken/perl_modules.html#document)
### Goals: ### Goals:
1. A well defined **specification**. This can be found in the [Specification](#specification) section. It is a constant work in progress; please open issues to discuss changes. 1. A well defined **specification**. This can be found in the [Specification](#specification) section. It is a constant work in progress; please open issues to discuss changes.
2. **An example README**. This Readme is fully standard-readme compliant. 2. **An example README**. This Readme is fully standard-readme compliant.
@ -123,6 +133,16 @@ A compliant README must:
**Suggestions:** **Suggestions:**
- If too long, consider moving to the [Background](#background) section. - If too long, consider moving to the [Background](#background) section.
- Cover the main reasons for building the repository. - Cover the main reasons for building the repository.
- This should describe your module in broad terms,
generally in just a few paragraphs; more detail of the module's
routines or methods, lengthy code examples, or other in-depth
material should be given in subsequent sections.
Ideally, someone who's slightly familiar with your module should be
able to refresh their memory without hitting "page down". As your
reader continues through the document, they should receive a
progressively greater amount of knowledge.
#### Table of Contents #### Table of Contents
**Status:** Required. **Status:** Required.