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:

http://sourceforge.net/projects/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:

http://www.winterwell.com/software/markdown-editor.php

README.md

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.

Contribution guidelines

example Guidelines should be made available once the code is available online and there is a process for external contributions. External contributions do not necessary mean from outside the eScience Center, it could be another engineer within the eScience Center. Good guidelines will save time of both lead developer and contributor since things have to be explained only once. GitHub supports CONTRIBUTING file.

Code of conduct

contributor covenant

CofC should be attached from the beginning of the project. There is no gain fro 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.

CITATION file

Make it easy to cite your software. Read more in the post by Robin Wilson This file should be human readable. Should point to the journal article if there is one and to DOI. More about obtaining DOI in DIO section.

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