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 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:
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:
Alternatively, 'pandoc' is a command line utility that can convert markdown documents to into several other formats (including latex):
An Eclipse plugin for previewing the HTML generated by markdown is available on this page:
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.
- StackOverflow on good readme
- short gist with README.md template
- The art of README from nodejs community
Well defined functionality
Ideally in README.md
Source code documentation
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 documentation should explain function arguments and outputs, or the object methods. How they are formulated will depend on the language.
- 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.
- 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 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:
- How to install the dependencies
- How to run (unit) tests
- What code style to use
- Reference to code of conduct
- When using a git branching model, the choice of branching model An extensive example is Angular.js's CONTRIBUTING.md. Note that GitHub has built in support for a CONTRIBUTING.md file.
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.
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
Identifiers should be associated with releases and should be created together with first release.
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