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?
Our motivation (but let us brainstorm first)
You will probably use your code in the future and may forget details.
You may want others to use your code (almost impossible without documentation).
You may want others to contribute to the code.
Shield your limited time and let the documentation answer FAQs.
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
README.rst can be enough (more about these formats later).
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:
Dalton (check the PDF manuals, e.g. Dalton 2018)
Motivation-2: Pros and cons of these examples
try to copy paste input snippets from the PDF
manual is generated manually by running LaTeX, so in practice it is often behind
no usage examples
one has to go into the source code to find out how to use it
contains copy-paste-able examples
contains recommended citation
no tutorials with clear narration
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.
Our wishlist (but let us brainstorm first)
Your code project should be versioned (version control).
Enable reproducibility and avoid confusion: documentation should be versioned as well.
Have you ever seen: “We will soon release a new version and are updating the documentation. Some features may not be available in the version you have downloaded.”?
Documentation should be placed and tracked close to the source code
Documenting close to the source code (e.g. subdirectory
doc/) minimizes barrier to contribute.
I should not need to log in to another machine or service and jump through hoops to contribute.
It is often good enough to have a
README.rstalong with your code/script.
Use a standard markup language
Markup is a set of human readable instructions that is used to tell the computer how a document shall be styled and structured. By using a markup language we can for example write a
- where we want a bullet point to appear in the rendered document.
offers formatting flexibility, enforces a basic document structure and the rendered documents can be exported to other formats (e.g. for printing). Also, the source can be read by humans without knowledge of the language in case the rendered document is unavailable.
We suggest to use either reStructuredText (RST) or Markdown markup.
GitHub and GitLab automatically render
PDF alone is not enough since copy-pasting out of a PDF document can be difficult.
It is OK to provide a generated PDF in addition to a copy-paste-able format.
Written by humans
Automatically generated documentation (e.g. API documentation) is useful as complementary documentation but it does not replace tutorials written by humans.
Give step by step instructions for the basic case. Additional information and caveats can be linked from there.
List requirements and dependencies (libraries, compilers, environment).
Include instructions for how to test for correctness after installation.
Make the license explicit
Include a LICENSE file with your source code.
Without a license, your work is under exclusive copyright by default: others are not allowed to re-use or modify anything.
GitHub and GitLab allows to choose a license from common license templates.
Information for contributors
Make it easy for others to contribute: document how you prefer others to contribute.
Users of your code may be shy to contribute code. Your documentation provides a platform for your first contributions.
Which items to include depends on the number of users apart from yourself.
Copy-paste-able example to get started
Dependencies and their versions or version ranges
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
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.