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?

(This is adapted from: What nobody tells you about 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

These are distinct. For an excellent discussion, please see What nobody tells you about documentation.

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

Own examples

Instructor note

  • One option is to discuss the examples below either as group discussion or in plenum.

  • As an alternative to discussing these examples you can also ask students:

    • Think of projects of which you like the documentation. What do you like about them?

    • Think of projects for which you don’t like the documentation. What don’t you like about them? Are you missing anything?

  • You can choose a mature library with lots of users for this exercise, but try to also think of less mature projects you had to collaborate on, or papers you had to reproduce.

We would like to show you some examples which are not ideal but we do not want to point at others. Instead we list some of the projects we have contributed to (possibly long time ago), with varying quality of documentation:

Motivation-2: Pros and cons of these examples

  • Dalton:

    • try to copy paste input snippets from the PDF

    • manual is generated manually by running LaTeX, so in practice it is often behind

  • Cubicle:

    • no usage examples

    • one has to go into the source code to find out how to use it

  • Numgrid:

    • contains copy-paste-able examples

    • contains recommended citation

    • no tutorials with clear narration

  • MNE-Python:

    • easy to select version of docs

    • has four “levels”: tutorials, how-to guides (examples), explanation pages and API reference

    • this level of documentation is overkill for small projects, but serves as a great source of ideas

Creating a checklist

Motivation-3: 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

Good resources


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

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

  • Use lightweight and standard markup languages such as reStructuredText or Markdown.