standard-readme/README.md

Standard Readme

Readme Standard Style

This repo is for standardizing how READMEs should look. The goal is to have:

• A well defined specification that other people could look to;
• An example README that can be used for comparison (this README.md is the example);
• A linter that can be used to look at errors in a given Readme;
• A generator that can be used to quickly scaffold out new READMEs.

There are many standards. This is mine.

** Table of Contents **

• Installation
• Usage
• Contribute
• Specification
  • Requirements
  • Sections
    • Name
    • one-line description
    • Table of Contents
    • Usage Section
    • API
    • Installation
    • License
  • Suggestions
    • Background section
    • Conventions
• License

Installation

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. There are plans to add a linter and a generator.

Contribute

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

Specification

Requirements

A compliant README must:

• Be called README.md (with capitalization).
• Be a valid Markdown file.

Sections

Name

Status: Optional.

Requirements:

• Must be first section.
• Must match repository name. If it cannot, there must be a note in the long description about why.
• Must match package manager name. If it cannot, there must be a note in the long description about why.

Suggestions:

• Should be self-evident.

Banner

Status: Optional.
Requirements:

• Must link to local image in current repository.
• Must appear directly after the title.

Badges

Requirements:

• If present, must go beneath banner (if present), or beneath title.
• Must be newline delimited.

Short Description

Requirements:

• Must be less than 120 characters.
• Must start with >
• Must be on it's own line.
• Must match the description in the packager manager's description field.
• Must match GitHub's description (if on GitHub).

Suggestions:

• Use gh-description to set and get GitHub description.
• Use npm show . description to show the description from a local npm package.

Table of Contents

Requirements: There must be a Table of Contents that links to the

Usage Section

Suggestions: Cover promises/callbacks, ES6 here.

API

Requirements: Describe internal objects and functions, signatures, return types, callbacks, and events. Types covered where not obvious. Caveats.

Installation

Requirements: Installation command. Suggestions: Link to prerequisite sites for language. [npmjs][], [godocs][], etc.

License

Requirements: State License. Suggestions: Link to longer License file.

Suggestions

Background section

Requirements: Motivation, abstract dependencies

Conventions

cb for callback num for Number int for Integer bool for Boolean etc.

License

MIT (c) Protocol Labs