Table of Contents
People read documentation in order to achieve a goal. Whenever you write a new piece you should keep their goal in mind.
For instance, you're currently reading this document. What is your goal? Maybe you want to improve the documentation of your own project, or perhaps you've been told this is an awesome document and your goal is simply to enjoy reading a beautiful text of astonishing beauty.
On the other hand I know you're a developer, so there's no point explaining what source code is. That would seem patronizing or a waste of time.
I also know that most of us don't speak English as a first language. Unnecessarily complicated words or sentences are then obstacles to our communication.
Finally, I know you're a diverse group. Among the readers of this document you'll find people from everywhere on the gender spectrum, different races, and different sensibilities. I do not wish to alienate any of them, so I need to be careful with the words I choose.
All of these concrete examples can be boiled down to the following best practices.
TL;DR:
- Audience: Everyone.
- Content: Description of the project and its current state. Links to other resources.
- Template: README.tmpl.md
- Example: https://github.com/twbs/bootstrap/blob/v4-dev/README.md
TL;DR:
- Audience: Contributors.
- Content: Steps necessary to modify the project, verify the changes, and contribute back to the project.
- Template: CONTRIBUTING.md
- Example: https://github.com/angular/angular.js/blob/master/README.md
TL;DR:
- Audience: Users of the project.
- Content: List of all of the features of the project with full information on arguments, flags, and others.
- Example: https://docs.angularjs.org/api
TL;DR:
- Audience: Contributors and users of the project.
- Content: New features, bug fixes, and other relevant changes since the previous version was released.
- Example: https://golang.org/doc/go1.9
TL;DR:
- Audience: New users of the project.
- Content: Detailed guide on how to accomplish something specific using the project.
- Example: https://docs.angularjs.org/tutorial
TL;DR:
- Audience: Contributors
- Content: Rules governing the contributor community and their interactions with each other.
- Example: https://www.contributor-covenant.org/