# Open Source Series: Documentation

Published 2020-02-16 · https://www.justjeb.com/post/open-source-series-documentation

An open source project without documentation is a dead project. There are basically two things that your documentation should contain — what and how. These are the cornerstones, the must-haves of documentation.

Hello and welcome to the third part of the “Open Source” journey. For those of you who haven’t read the previous parts or wonder what is the planned content for the next parts:

## Table of contents

1. [Intro](https://www.justjeb.com/post/owning-an-open-source-part-1)

2. [Starting a Project](https://www.justjeb.com/post/owning-an-open-source-project-part-2)

3. **Documentation**

4. [Publicity](https://www.justjeb.com/post/open-source-series-publicity)

5. [Issues and PRs](https://www.justjeb.com/post/open-source-series-issues-and-prs)

6. [Automation](https://www.justjeb.com/post/open-source-series-automation)

7. [Version management](https://www.justjeb.com/post/open-source-series-version-management)

## Recap

In the previous parts we’ve discussed what Open Source is and how one can start a new open source project.  The first two parts were targeted to those who consider creating an open source project, to let them know what to expect and give them some headstart in the open source world.

This part, as well as the coming ones, will also be relevant to the people who already maintain an open source project and help them improve at what they do.

### The baseline for this part:

> You already have an open source project, it is available on Github and it can be consumed easily via one of the package registries.

If you have no idea what I’m talking about I suggest you to read the first two parts.

## So here we go

> An open source project without documentation is a dead project

It is dead because no one will dive into your code to find out how it should be used. And even before *how*, no one even knows *what* your code is supposed to do.

So these are basically the two things that your documentation should contain — *what* and *how*. These are the corner stones, the must-haves of documentation.

## Description

Description is the first thing everyone sees upon entering a Github repository. Therefore a good description should answer in a short and informative manner to the *what* question. For example:

[React](https://github.com/facebook/react):

> The library for web and native user interfaces. [https://react.dev](https://react.dev/)

[Moment.js:](https://github.com/moment/moment)

> Parse, validate, manipulate, and display dates in javascript. [http://momentjs.com](http://momentjs.com/)

[Angular builders](https://github.com/just-jeb/angular-builders) (this one is mine):

> Angular build facade extensions (Jest and custom webpack configuration)

The description can be edited by clicking on the Edit button at the top right of your repository:

![The GitHub header of the just-jeb/angular-builders repository in dark theme, with the tab row Code, Issues 36, Pull requests 2, Actions, Projects 4, Wiki, Security, Insights, Settings above the description line "Angular build facade extensions (Jest and custom webpack configuration)", and the Edit button at the far right circled in green](https://www.justjeb.com/_astro/img-02.hf7J3hzI_2uv3vb.webp)

## README.MD

README.MD is a file in the root directory of your project written with [Markdown syntax](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax), which contains all the information one needs to know about your project.

The README file should contain a detailed description (which expands on the *what* question) and very detailed instructions on *how* to use your project.  The instructions should cover every single piece of *public API*, preferably with usage examples.

A few points for writing a good API documentation:

- **Keep it simple:** *The simpler the API and the example — the easier for a user to understand what it does or how to use it*

- **Keep it structured:** *Use the same template and visual structure for every API method, this way you’ll define your own language for communicating the API to the user*.

- **Be a user:** *Always write API description from the user’s perspective. Assume that you know nothing about the internals and this documentation is all you have.*

- **Keep it up to date:** *As your project evolves the APIs might change. Make sure that your README file always contains the most actual APIs and examples*

The README can (but doesn’t have to) contain the following things:

- Link to a contribution guide

- List of contributors

- Link to a change log

- Latest version

- License

- Build status

- Downloads counter

- Link to a chat for fast feedback

## Badges

Badges are a fairly good way to visually expose the essential info about your project, such as: build status, version, license and various tools used by your project. There are quite a few options but I’d recommend you use [shields.io](https://shields.io/) badges.  They have a badge for literally everything.

Adding a badge to your README file is really simple:

1. Go to [shields.io](https://shields.io/)

2. Choose the appropriate category

3. Click on a badge you’d like to add to your README

4. Fill in the required information (if any)

5. Choose Markdown from the format tabs and press Copy

6. Paste the markdown into your README file

![The shields.io badge builder for an npm (scoped) badge, with scope @angular-builders and package name custom-webpack filled in, a style dropdown set to flat and empty optional fields for override label, override color, named logo and override logo color, the resulting npm v8.4.1 badge previewed underneath, and the Copy Badge URL dropdown open with its Copy Markdown entry circled in green above Copy reStructuredText, Copy AsciiDoc and Copy HTML](https://www.justjeb.com/_astro/img-03.1YgPw68K_Z1sm7hC.webp)

The badges are usually put at the top of the README file right before the detailed description. This is what it looks like:

![The top of a README rendered on GitHub in dark theme, showing a gitter join chat badge, then a row of shields.io badges reading npm v2.24.0, downloads 38M/month, license MIT, build passing, coverage 88%, license scan passing and semver stability 97%, and below them the description "A lightweight JavaScript date library for parsing, validating, manipulating, and formatting dates."](https://www.justjeb.com/_astro/img-04.BOZoY0rD_PiryQ.webp)

## Tests

API reference is great, but nothing compares to a real code using your public APIs.  One of the best ways to complement your documentation is having a good code coverage with descriptive tests. Sometimes tests explain the code better than any documentation.

## Wrapping it up

In this part we’ve only covered the basics of documentation. It has a lot more than just a README or a description, for example, as your project grows and issues arise, they become an integral part of the documentation.

> However, having a README file that covers the public API is the bare minimum for any decent open source project