Skip to content

Table of Contents

Documentation

General Best Practices

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.

State A Clear Goal

Define A Scope

Keep It Simple

Don't Alienate The Reader

Keep Accessibility In Mind

Arbitrary Choices And Consistency

Documentation Artifacts

README.md

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

CONTRIBUTING.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

Reference Material

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

Release Notes

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

Guides/Tutorials

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

Code of Conduct

TL;DR:

  • Audience: Contributors
  • Content: Rules governing the contributor community and their interactions with each other.
  • Example: https://www.contributor-covenant.org/

Issue Templates

Other Pieces Of Documentation

Resources

Last update: April 8, 2024
Created: July 24, 2023