Posted by s.hettrick on 3 May 2012 - 11:20am

By Aleksandra Pawlik, Agent and PhD student at the Open University.

1. Think about your audience

Depending on the nature of your software you will need different documentation for different audiences.

The first group, which you always have to address, are your users. Who are they? If you make assumptions about the level of their knowledge, both science- and IT-related, make sure that you list these assumptions in your documentation.

The second group are users-developers, or just developers. The former are scientists who not only use your software, but also develop new modules in order to progress their research. The latter may be software engineers who support a group of scientists that use your software.

The final group are people who maintain and provide IT infrastructure at research institutions. If your software needs to be installed on a server or a cluster, you should provide documentation that enables an administrator to set it up and support its use.

2. Quick start or no start at all

If you do not have the resources to provide comprehensive documentation, a quick-start guide is a minimum requirement.

You should clearly explain to your users how to get your software up and running. If they struggle to even start to work with the software, a potential user might abandon it and search for an alternative instead. I recently encountered a very useful software package for climate research which, despite its great features, was replaced with a spreadsheet by some users. The software had less than a modest README file, and the steep learning curve had successfully discouraged new users.

3. Can you see the big picture?

Source code comments are a great way to capture the details of implementation. An exhaustive API is also a valuable piece of documentation. However, detailed descriptions should be complemented by “high level” documentation related to the software architecture, dependencies (call tree) and so on. This information is particularly important if you want other scientists to add to your source code, because contributing to software requires an overall picture of the software - not just a knowledge of the arguments and functions.

4. Invisible documentation

Software developers typically loathe writing documentation, and most scientists-developers are no different. However, the task might be easier than you imagine, because of pre-existing invisible documentation.

A lot of information about the software may already have been captured. Meaningful commit messages can be very informative. Entries in an issue tracker together with a discussion related to them can provide a lot of detail about the software. Emails exchanged within the development team or the logs from internet messengers can provide information and track decisions made about the software's design. If you can access this information and tie it together, you could start your documentation with relatively little work.

5. Engage the user community

There is probably no one who knows your software better than… an experienced user who has been intensively using your software. He or she has probably seen runtime errors or compiler warnings that you would never expect to be there! This knowledge can be invaluable for other users and users-developers.

A discussion forum or a mailing list related to your software can generate incredibly rich information about your software and may successfully serve as documentation. If you open your source code, why not open your documentation too? This way you can encourage users to contribute to it. SciPy is a good example of effective crowd-sourced documentation. User communities have a great potential for documenting software and it can be very rewarding to engage them in this activity.