Documentation

Developed programs should be documented at multiple levels, from code comments, through API documentation, to installation and usage documentation.
Comments at each level should take into account different target audience, from experienced developers, to end users with no programming skills.

Example of good documentation: A Guide to NumPy/SciPy Documentation

Markdown

Markdown is a lightweight markup language that allows you to create webpages, wikis and user documentation with a minimum of effort. Documentation written in markdown looks exactly like a plain-text document and is perfectly human-readable. In addition, it can also be automatically converted to HTML, latex, pdf, etc.
More information about markdown can be found here:

http://daringfireball.net/projects/markdown/

http://en.wikipedia.org/wiki/Markdown

Retext is a markdown aware text editor, that can be used to edit markdown files and convert them into HTML or PDF. It can be found at:

https://github.com/retext-project/retext

Alternatively, ‘pandoc’ is a command line utility that can convert markdown documents to into several other formats (including latex):

http://johnmacfarlane.net/pandoc/

An Eclipse plugin for previewing the HTML generated by markdown is available on this page:

https://marketplace.eclipse.org/content/markdown-text-editor

Readme

Clear explanation of the goal of the project with pointers to other documentation resources.

Use GitHub flavoured markdown for, e.g.,
syntax highlighting.
(If reStructuredText or another format that GitHub renders is idiomatic in your community,
use that instead.)
README is targeted towards developers, it is more technical than home page.
Keeping basic documentation in README.md can be even useful for lead developer,
to track steps and design decisions.
Therefore it is convenient to create it from the beginning of the project,
when initialising git repository.

Well defined functionality

Ideally in README.md

Source code documentation

Code comments

Code comments, can be block comments or inline comments. They are used to explain what is the piece of code doing. Those should explain why something is done in the domain language and not programming language - why instead of what.

API documention

API documentation should explain function arguments and outputs, or the object methods. How they are formulated will depend on the language.

Usage documentation

  • User manual (as PDF) in the “doc” directory. This is the real manual, targeted at your users. Make sure this is readable by domain experts, and not only software developers. Make sure to include:
    • Netherlands eScience Center logo.
    • Examples.
    • Author name(s).
    • Versions numbers of the software and documentation.
    • References to:
      • The eScience Center web site.
      • The project web site.
      • The Github page of the project.
      • Location of the issue tracker.
      • More information (e.g. research papers).

Documented development setup

(good example is Getting started with khmer development)
It should be made available once there is more than one developer working on the codebase. If your development setup is very complicated, please consider providing a Dockerfile and docker image.

Contribution guidelines

Contribution guidelines make it easier for collaborators to contribute, and smooth the process of collaboration.

Guidelines should be made available once the code is available online and there is a process
for contributions by other people. Good guidelines will save time of both lead
developer and contributor since things have to be explained only once. A good CONTRIBUTING.md
file describes at least how to perform the following tasks:

Code of conduct

A code of conduct is a set of rules outlining the social norms, religious rules and responsibilities of, and or proper practices for an individual. Such a document is advantagous for collaberation, for several reasons:

  • It shows your intent to work together in a positive way with everyone.
  • It reminds everyone to communicate in a welcoming and inclusive way.
  • It provides a set of guidelines in case of conflict.

contributor covenant

CofC should be attached from the beginning of the project. There is no gain from having it with one
developer, but it does not cost anything to include it in the project and will be handy when more
developers join.

Documented code style

From the beginning of the project, a decision on the code style has to be made
and then should be documented. Not having a documented code style will highly
increase the chance of inconsistent style across the codebase, even when only
one developer writes code. The Netherlands eScience Center should have a sane suggestion of coding style
for each programming language we use. Coding styles are about consistency
and making a choice, and not so much about the superiority of one style over the other.
A sane set of guides can be found on in google documentation.

How to file a bug report

Describing how to properly report a bug will save a lot of developers’s time.
It is also useful to point users to good bug report guide like one from Simon Tatham

Explained meaning of issue labels

Once users start submitting issues labels should be documented.

DOI or PID

making your code citable

Identifiers should be associated with releases and should be created together with first release.

Software citation

To get credit for your work, it should be as easy as possible to cite your software.

Your software should contain sufficient information for others to be able to cite your software, such as: authors, title, version, journal article (if there is one) and DOI (as described in the DOI section). It is recommended that this information is contained on a single file.

You can use the Citation File Format to provide this information on a human- and machine-readable format.

Read more in the blog post by Druskat et al..

Print software version

Make it easy to see which version of the software is in use.

  • if it’s a command line tool: print version on the command line
  • if it’s a website: print version within the interface
  • if the tool generates the output: output file should contain the version of software that generated the output