By Mike Jackson.

A checklist for developers

To get people using your software as quickly and painlessly as possible, you should invest a little of your time preparing everything your users will need before you release your software. This guide describes some simple things you can do to improve your users' experience of your software.

Why write this guide

We wrote this guide to give an overview of a subject that we think is important to software sustainability. It's derived from a checklist used when releasing the successful OGSA-DAI software.

Do you provide contact information?

A user might want to contact you if they have a problem, they want to report a bug or need more information. And it's not all one-way, your users might contact you to provide you with bug fixes or collaborate with you. You should also provide an easy way for a user to get in touch. At a minimum you should provide:

• Your website address
• An email address. Ideally, this will be a project or product email address that is received by more than one person so that replies to the user aren’t delayed if someone is on leave
• To reduce the number of enquiries you receive, you should also provide the location of documentation

Contact details can be provided in a README, your documentation, in a help menu command (for graphical user interfaces) and on your website. To make life easy for your users, you should supply contact details by all of these means and any others at your disposal.

Does your software have version information?

Version information, such as a version number or a release date, is very useful, because it helps users know if the release is new. Version numbers also provide users with an expectation about the changes made from one release to another: a change from version 2.0 to 3.0 will lead to an expectation of major changes, whereas a change from 2.0 to  2.0.1 indicates more minor enhancements and bug fixes.

When a user asks for help they can cite the release date or version number and you'll be able to understand their problems much more quickly. For example, knowing the version number can help resolve a common Java problem of JARs from different versions being in the same CLASSPATH.

Version numbers help when instructing expert users to upgrade existing deployments, for example by telling them to 'replace all 2.0 DLLs with 2.0.1 DLLs'.

You can keep track of your software by branding it with a release date or version number. For this reason, the release date or version should be added to your download bundle, executables, libraries, the help or about menu, READMEs and other documentation.

Do your library names include your product name?

Including your product name in your library shows users which libraries are yours, and which belong to third parties. This makes it easier for users to upgrade your software and, for open-source software, experiment with bug fixes or extensions. A simple naming scheme would include the product name, a component name (if your software has multiple components) and a release date or version number:

• ssiproduct-syntaxparser-1.2.jar
• ssiproduct-visualiser-1.2.jar
• ssiproduct-utilities-1.2.jar

Does your release bundle unpack to a single directory?

If you intend to bundle your software as a zip or tar file (or any archive format), it is safer to pack it as a single directory and then name the bundle after the directory. For example, put all the files in ssiproduct-1.3.23/ and then zip or tar the directory to create ssiproduct-1.3.23.zip (or ssiproduct-1.3.23.tar).

If you don't follow this advice, and simply zip up all the files from a directory, then when a user unpacks the bundle they will find the files spread all over their current directory. Users will have to waste their time cleaning up directories, or worse, the user’s files may be overwritten by your unpacked files if they share the same names.

Do you specify your copyright and have a licence?

Copyright allows you to state that you own what you have written. A licence sets down the terms under which you are releasing what you have written, the conditions under which it can be used, who owns the copyright and who is liable if things go wrong. A licence also sets down the conditions under which users can modify, extend or exploit your software.

If you do not provide this information, then users will not know whether they can use your software. Some users will not use it, and others will assume they're free to do whatever they want with your software. They could pass your work off as their own and sell it. They might accidentally corrupt their critical data, lose hundreds of thousands of pounds and then pursue you for damages. You may be unhappy at having lost out on a share of the former, or being dragged into court over the latter. For an introduction to copyright and licensing, see our guide on adopting an open-source licence, or the OSSWatch guide on open-source development - an introduction to ownership and licensing issues. In addition to these guides, most organisations (universities especially) will have legal experts who will provide more tailored advice.

Depending on the application of your software, you might consider a disclaimer. The following disclaimer was used with medical software.

This software has neither been tested nor approved for clinical use or for incorporation in a medical device. It is the user’s responsibility to comply with any applicable local, state, national or international regulations.

You can provide copyright and licence information in a README, your documentation, in a help menu command and on your website. You could go further: some products require a user to accept their terms and conditions before they can be downloaded or installed.

For C, C++ and Java you can also define constants to embed your copyright in binaries:

private static final String COPYRIGHT_NOTICE = "Copyright (c) ....";

For Java, you can also embed copyright and licence information in META-INF/MANIFEST.MF files in your JAR files:

Manifest-Version: 1.0 Implementation-Title: SSI Product Implementation-Version: 1.0 Implementation-Vendor: The University of Edinburgh. Copyright: Copyright (c) The University of Edinburgh, 2011. Licence: Apache 2.0. WWW: https://www.software.ac.uk

If you release your source code, you can add the information described above as comments to your source files. This means that users can see the copyright and licence even if the file is separated from the rest of the source code, or if you expose your code repository online:

// Copyright (c) The University of Edinburgh, 2011. // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, // software distributed under the License is distributed on an "AS // IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either // express or implied. See the License for the specific language // governing permissions and limitations under the License.

Do you respect third-party copyright and licensing?

When developing with off-the-shelf components, you can use or bundle other peoples' software. Each of these will have their own copyright and licencing conditions. It is up to you to ensure that the terms and condition are respected. Make sure that you do not remove the copyright statements from other peoples' software or violate the terms of their licences.

Take Apache 2.0 for example. If you include software licensed under Apache 2.0, it is a condition that you must also make available a copy of the Apache 2.0 licence. If you have modified the Apache 2.0-licenced source code, it is a condition that the modified source code must be commented to show where and how you have changed it.

It is important to remember that having the source code for software (even if it's open source) does not mean that you are free to use it as you wish. You do not automatically have the right to redistribute the source code or modify it. The source code's licence might not even give you ownership over any changes you make. Everything depends on the licence, so make sure you have read it and respected the terms.

If your software includes third-party products, it is useful to provide users with a list showing:

• Which parts of the software are third-party products
• The version numbers or release dates and project websites of the third-party products
• The third-party licences
• The files in your release bundle that derive from third-party products

Are your text files free from platform-specific control characters?

Sometimes text files that are written under Windows can contain odd characters when viewed under UNIX/Linux, or vice versa:

* SSI Software Licence - SSIProduct (1.0)  SSI Software Licence â SSIProduct (1.0)

You should check that all project files use common character encodings and that the character sets look okay on all platforms. This is especially important for shell scripts since the presence of ^M newline characters, which often appear in text files written on Windows, can cause errors when the shell scripts are run under Linux/UNIX:

./run.sh bash: ./run.sh: /bin/sh^M: bad interpreter: No such file or directory

The user could edit the shell scripts and remove the ^M characters, but if you remove the characters you also remove a barrier to using your software.

Are your instructions precise and accurate?

Your users are busy people. They won't want to spend time hunting for third-party dependencies, configuration files, parameters in files and commands in menus. Nor will they want to spend their time trying to execute commands only to discover there was a typo in the user documentation. You are likely to lose a potential user if they have to spend a lot of time trying to solve problems that wouldn't exist if the information you provided was precise and accurate. It is far easier for you to provide precise and accurate information than for your users to hunt around for it themselves.

Make sure that the user documentation exactly matches your software. There are a lot of factors to consider, such as screen-grabs of GUIs, command names and arguments, configuration file properties and values, code fragments, Java packages and Java and C++ class names. The small difference between a.b and a b can cause major problems for users.

When instructing a user, make sure that your instructions are clear and unambiguous. When referring to commands, menus, buttons, parameters or arguments, don't just give a description - name it exactly. In other words, don't say 'Edit the input directory parameter', but say 'Edit the input directory parameter (called input.dir)'. Ideally, provide an example too: 'input.dir=$SSIPRODUCT/images/medical'. The same applies to files in sub-directories. Avoid saying 'Edit the index file in the medical images directory', and instead say 'Edit the medical images index file $SSIPRODUCT/images/medical/index.txt'. With GUI menus, specify each menu and sub-menu. Instead of saying 'select the load command from in the file menu', say 'Select the File=>Load=>Load File... command'.

Can a user build your source-code bundle?

If you release a source-code bundle, be sure to provide accurate and precise instructions for building the code. Make sure you document the supported platforms and programming language(s) required, the third-party products required and a description of what they’re used for, and how to build the software. When describing the third-party products,make sure you specify:

1. product or project name
2. project website URL
3. the version of the product
4. the download URL (if possible, otherwise provide a description of the links the user must follow to access the download)
5. why the product is needed

Always follow the build instructions yourself (even if you have a build file) on a machine that you do not usually use for development. This allows you to test that your instructions would allow a user to build your software in a fresh environment. 

Do you claim your software is "easy to use"? If so, think again…

Don’t ever claim that your software is easy to use - not in your user documentation and not on your website. Likewise, avoid terms like user friendly, intuitive, simple or obviously.

By all means quote satisfied projects and users but, as you wrote your software, you are an expert in it, so you don’t have the right to make such claims yourself. It can be demoralising for a user to see easy to use when they’ve spent a morning trying to run your software without success. They may be inclined to let others know of their views on how easy to use your software really is.

Likewise, avoid the popular, but inaccurate, phrase user friendly graphical user interface and its variants. A GUI is not necessarily user friendly (and something user friendly doesn't necessarily have a GUI!).

Have you downloaded your release?

If you've uploaded your release and it's ready for publicising to your users then congratulations! You’re almost there… but there is one more test you must do. Download your software and unpack it. This allows you to check that your download links work and the software bundles are not corrupted. It’s better that you find out now than your users find out for you.