By Mike Jackson.

How will you support your software?

You want to release your software under an open-source licence so that others can benefit from its use. How do you support your software, handle questions from users, resolve bugs and what are the support overheads? The Software Sustainability Institute can provide advice on what is required from support, and the best techniques and tools for delivering support.

1 Why write this guide?

We wrote this guide to give an overview of a subject that we think is important to software sustainability.

2 What users want to know

When it comes to software, we have found that there are a few things that users generally want to know.

2.1 What does it do?

This is the first and most basic question a user will ask. You should be able to answer it succinctly - preferably in one sentence - using as little jargon as possible. By answering this question, you help a user to decide whether your software meets their requirements.

2.2 How do I use it?

You've got a user interested, but how do you make sure they'll stick with your software? You must be able to provide clear, precise and correct instructions that describe how to use your software. One of the main reasons why users abandon software is that they are stuck with a mysterious black box and no easy way of understanding it.

It's not just documentation. Some users will want to get started quickly, others will want to see how the software is used. Support your documentation with as many other resources as you can manage. Quick-start guides, tutorials, screencast demos can all help your users gain a better understanding of your software.

2.3 Are there any known issues?

No-one likes to spend time battling with a problem only to be told "ah... we've known about that for weeks". A list of known issues has a two main benefits. The first is that a user can check to see whether the problem they have found is new. The second is that after a user has seen the known issues, they understand what they're buying into when they use your software. Expectation management is important, especially with early development or prototype software which unlikely to be bug free.

2.4 Where do I ask for help?

If a user has a question, they will want to know who they can ask for an answer. Provide a list of contact details on your website and on any help resources, such as documentation, that you produce.

2.5 Did you hear me?!

Support overheads kick in at this point. Users want answers quickly, and will be happy with speedy responses. However, you may only provide support on a best-effort basis. Be straight with your users! Wherever you list your help resources, you should also describe the level of support that users can expect. Managing expectations of support means that you won't end up with disgruntled users. It's easy for "I didn't get a reply" to evolve into "that software doesn't work" and then into "that project sucks".

2.6 How long will your project be around?

If your software is going to form a critical part of a user's project, then they will want reassurance that support will be around for as long as they need it. No one can predict the future, but you can be clear about your plans for the future.

3 How to solve user queries

Before dealing with a query, it's a good idea to try and understand the wider context of their query. What is the user trying to do and why? Simply answering the question they asked may be all that's needed, but sometimes the user is struggling with a bigger problem. If you can provide hints on how to deal with the big problem, or at least ask whether they need help with it, you could end up dealing with a query before it ends up as a string of follow-up queries. And you'll produce one extremely satisfied user. Sometimes the user's problem is not with the software, but how they are trying to use it. Sometimes, it's the way in which the user's trying to solve their problem. Establishing the context of a user's query may reveal solutions that better match their requirements than dealing with the query as a quick fix.

Sometimes you'll deal with a query and not hear back from the user. Hopefully, this will happen because the solution worked, but it could happen because the user hasn't had time to try the solution or they've run into more problems. Either way, it's useful to follow up with the user and see how they're getting on. This also helps you improve your support: maybe the solution needed a few changes before it worked, or maybe the user found discovered another, better fix.

3.1 Manage your support

Ticketing systems, also known as bug and issue trackers, are very useful within a project. Rather than managing queries yourself, a ticketing system will show:

• All open and unaddressed queries
• Who is working on which query
• Which queries have been completed, postponed or abandoned and why
• Which bugs have been fixed, can't be reproduced or can't be fixed and the reasons why
• Current progress and options explored to date
• Priority and severity

It can be beneficial to open up your ticketing system to users too. This gives users a more direct route to finding the status of their query. Even providing read-only access to users can be useful, because it allows them to:

• See if their query has already been reported and solved.
• Track the progress that's being made to a solution.
• See the your many tasks and TODOs, which may help them understand a delay in responding to their query.

3.2 Let users know the level of support you offer

By supporting your software you are offering a service and, like all services, this takes time and effort. What support you offer is up to you. You'll need to factor in the time and effort you have, your other commitments, deadlines and the goals of your project. You don't want to be overwhelmed with queries you can't answer, or to cause upset because you can't give a user's query the attention it needs. Expectation management is important, so it is advisable to be honest about the level of support you offer and to publish this information. When describing the level of support you provide, there are three aspects to address:

• Quality of Service, which is a description of how you'll perform support. Will you reply to all e-mails within 24 hours, within a week, or on a best-effort basis. The quality of service is determined by the resources available for support, and it is advisable to make this clear to your users.
• Scope of Service, which is the products you support. You might not support releases built by your users from your repository, or you might only support your software's use on recommended platforms.
• Types of Service, which is type of help you will provide. You might provide advice on developing tailored solutions to complex issues, or maybe only provide support on the resolution of bugs.

Once you've published your level of service, it is vitally important to respect and conform to it. It's not the end of the world if circumstances change and you can no longer support the level of service you've published. Although it's great if you find that you can improve the level of service. Either way, make sure that you quickly redefine the quality, scope and type of service you offer, and then ensure that your user base is aware of the new level of service.

If your software is to form a critical part of a user's project, they will want to know how long you'll be around to support it. They may want support over the lifetime of their project, or for long enough so that they can deploy the software and learn how to use it.

4 How will your users contact you?

There are many different ways that a user can get in touch to ask a question about your software. Over time, email has emerged as one of the contact methods of choice in the software industry. Email provides a low cost way of supporting users, and it allows them to submit a question at any time of night or day.

Email lists offer several advantages over traditional e-mail:

• Any subscribed user will be informed of a question submitted by anyone and your response. This means that you can answer one user's query and, at the same time, help any other users who have the same problem but has yet to ask for help.
• Users can share experiences and help each other. You may find that users come to support other users without you having to intervene. Free support from your user base!
• The mailing list provides an easy way to contact all users and let them know about information, issues or bugs that you have found. These are termed advisories.
• Emails to the list can be stored and published as searchable archives. This provides users with a basic FAQ resource that they can search. If a user finds their answer in the archive, they won't need to contact you, which reduces your support overhead. What's more, you can use the archive to gain an understanding of the uptake of your software.

There are alternatives to email and mailing lists. Public forums can act as an alternative to e-mail lists, although they do have the disadvantage that they require a users to visit the forum's website. RSS feeds offer a way of notifying users when questions are asked and solutions published. Many users would appreciate a telephone number, because it provides direct contact with the developer. However, few open-source developers have the resources needed to support such a service.

If users can contact you in a variety of different ways, they will use them all to contact you. Although there is nothing fundamentally wrong with receiving support queries in a variety of different ways, it helps with the management of queries if you can limit how they are received. This allows you to maintain an accurate picture of current, which makes it easier to assess queries and prioritise them. It also ensures that all answers to queries are recorded (in the e-mail list archives or on the ticketing system) for future use.

The first step to control how queries are received is to make it clear which contact methods are used for queries. This advice should be apparent from your website and any publicity materials that deal with support. If you receive a query through a non-agreed contact method, you can politely redirect users to submit their query via your preferred means of support. Although it might be advisable, from a customer service perspective, to deal with the query and ask the user to submit their next query through the agreed means.

5 What about real-time support?

It can sometimes be useful, for both users and yourself, to discuss problems and work through issues in real-time. It's often easier to lead a user through a sequence of steps than describe them in an email. Real-time support also allows you to react to problems as they occur. Real-time support can be provided over the phone or by using a chat program.

Probably the most effective way of dealing with a query is to meet up with the user so you can see what's happening. This option is limited by the user's proximity and your support budget, although you might consider this option for VIP users. You could invite the user to your office for a day, ask for them to pay for you to travel to them or arrange to meet up at a conference that you are both attending.

More generally, if time and money permits, you might consider organising a support event. This could be a stand-alone event, it could occur alongside an existing event, such as a conference. Users can be invited to come and discuss their problems with you. This way, you get to meet your users and deal with a substantial number of queries at the same time. These events also give you the opportunity to invite users to share their experiences, walk through tutorials or solve problems of common interest. This is a useful way of building a community around your software.

6 Other support resources

6.1 FAQs

E-mail exchanges can become complicated. Once a problem has been resolved, you could write out the solution so that it is easy to understand and add it to a list of frequently asked questions (FAQs).

6.2 Tutorials and how-tos

Sometimes documentation provides too much detail, and users simply want to know how to perform one specific task. How-tos and tutorials provide users with a focussed description of how to complete a specific task.

Wikis, blogs and website are all good ways of publishing tutorials and how-tos. You could also make use of your community by allowing your users to publish their own tutorials and how-tos.

6.3 Source-code repository

Exposing your source-code repository, even in a read-only state, provides a way of helping users who are also developers. A source-code repository allows users to get access to bug fixes as soon as they have been made.