Motivation and wishlist


Motivation-1: Why documenting code?

Use the collaborative document:

  • Is project documentation important? Why?

  • How would you describe a useful documentation?

  • How can you motivate your colleagues to contribute to the documentation?

What do we expect from a suitably good documentation?


Documentation comes in different forms - what is documentation?

  • Tutorials: learning-oriented, allows the newcomer to get started

  • How-to guides: goal-oriented, shows how to solve a specific problem

  • Explanation: understanding-oriented, explains a concept

  • Reference: information-oriented, describes the machinery

Read more:

There is no one size fits all: often for small projects a or README.rst can be enough (more about these formats later).

Creating a checklist

Motivation-2: Create a wishlist

Use the collaborative document:

  • Let us create a wishlist for how we would like documentation to be.

  • Below are some of our ideas but please do not look at them yet.

  • We are sure you will come up with ideas we did not think about.

Documentation checklist

Which items to include depends on the number of users apart from yourself.

  • Purpose

  • Authors

  • License

  • Recommended citation

  • Copy-paste-able example to get started

  • Dependencies and their versions or version ranges

  • Installation instructions

  • Tutorials covering key functionality

  • Reference documentation (e.g. API) covering all functionality

  • How do you want to be asked questions (mailing list or forum or chat or issue tracker)

  • Possibly a FAQ section

  • Contribution guide


  • Documentation is part of the code and should be versionable.

  • Documentation (sources) should be tracked with the corresponding code in the same repository.

  • Use standard markup languages such as reStructuredText or Markdown.