Skip to content

Documentation

When open-sourcing a project, it's crucial to provide adequate documentation. Users and potential contributors are often not in direct contact with you, which makes it very important to clearly explain what the project is about and how to use it.

README

A README file provides a way to give essential information to users. For simple projects, providing a detailed README might contain all the documentation that is needed. Usually it's written using the Markdown lightweight markup format and put in the README.md file at the root of the repository.

It should contain:

  • The name of your project
  • A very brief and clear description of what it is and why the reader might be intersted in it
  • Information on how use it
  • Information on how to contribute (often separated into a dedicated CONTRIBUTING.md)
  • Authors and acknowledgments
  • Links to other resources (project website, more extensive docs, similar projects, etc.)

See the list of awesome READMEs for inspiration.

Documentation website

If more extensive documentation is needed, you need to set up a documentation website. There are many options for how to generate the website and where to host it, so we only present a few convenient options.

CERN documentation website

It's very easy to set up a documentation website at CERN. The Markdown sources are managed through a gitlab.cern.ch repository. On every commit to the main branch, it gets automatically transformed into a website by mkdocs and published on a docs.cern.ch subdomain hosted on Gitlab pages. The main drawback is that external contributors without CERN accounts can't directly contribute to the documentation. This website is generated by mkdocs!

GitHub pages

Alternatively, the documentation can be hosted on GitHub pages. This is particularly convenient if the code is also hosted on GitHub and you expect external contributions to the documentation too. For simple uses you could use the built-in Jekyll templating system, but it's not really meant for documentation. If you want to have a similar workflow to the previously mentioned mkdocs CERN-hosted documentation, you can set-up Material for mkdocs to publish to GitHub pages.

Read the Docs

Another option is to use a dedicated platform to host the documentation. Read the docs is a popular platform which offers convenient features such as integration with the git repository to update the documentation automatically, a simple build process through a configuration file, and automated versioning allowing users to easily access documentation for previous releases.