generator-make-readme
Quickly generate standards-compliant READMEs for open source software projects.
Overview
This Yeoman generator conforms to the standard-readme specification with some added customizations to comply with AffiniPay's supplemental README standards. It creates a minimally compliant standard README for your open source software project.
Table of Contents
Background
Github is an important platform for collaborative software development. It's also a channel for AffiniPay to share tools with our partner/developer community. We need to provide concise, accurate, and standardized documentation for all AffiniPay open source projects.
Standardizing our READMEs makes creating and maintaining them easier, promotes a better developer experience, and helps us earn trust within the partner/developer community.
An effective README thoroughly explains:
- What a project does (with context)
- What a project looks like in action
- How to install it
- How to use it (with working examples)
- All API methods/functions
This project is a customized version of Richard Littauer's generator-standard-readme project, but it follows the same specification.
Installation
This generator requires node, npm, and yeoman.
You can install it by itself by running:
npm install --global generator-make-readme
With Yeoman
You can also install it as a standard Yeoman generator by installing yo:
npm install --global yo
Usage
$ make-readme
With yo:
yo make-readme
This will write a file (README.md) to the local directory after you follow the prompts in a terminal.
Fields to fill out
The make-readme generator prompts you for information to create a README outline that contains all optional and required sections. These sections contain placeholder text and examples that you must modify before publishing the README.
Prompts include the following:
- What is the name of your project? - Defaults to the name of the repo.
- Summarize your project in one sentence: - You can add more detail later in the Overview and/or Background sections (if necessary).
- Do you have a banner image? - Optional.
- Do you want a standard-readme compliant badge? - Optional.
- Do you want a TODO dropped where more badges should be? - Optional.
- Do you want to add a prioritized Security section to the top of the README? - Optional.
- Do you need a Configuration section? - Optional.
- Do you need a Background section? - Optional.
- Do you need an API section? - Optional.
- Are pull requests accepted? - If true, adds a Contribute section with default guidelines.
- Is an MIT license OK? - If false, enter the license type in the next prompt (e.g., ISC). Make sure to update the license file in the repo.
- Who is the license holder? - The default is AffiniPay LLC.
Contribute
Contributions in the form of GitHub pull requests are welcome. Please adhere to the following guidelines:
- Before embarking on a significant change, please create an issue to discuss the proposed change and ensure that it is likely to be merged.
- Follow the coding conventions used throughout the project, including 2-space indentation and no unnecessary semicolons. Many conventions are enforced using eslint.
- Any contributions must be licensed under the MIT license.
License
MIT © AffiniPay LLC