How to communicate with techs

Version 0.9.1

• Introduction
• Constraints on techs
• How to solve a problem
• How to report a problem
• Where to send your message
• How to interpret the response
• Sharing what you've learned
• Requests for general information
• Complaints and suggestions
• Documentation
• Reports
• Conclusion

Introduction

Users are often frustrated when information technology doesn't seem to work, or when it doesn't work the way they expected. Volunteer techs (system administrators and software developers) are often frustrated with the way users communicate with them, particularly when reporting problems and asking for assistance. When techs don't respond the way users want them to, this only irritates the users even more. This document provides guidelines for users, so that they can solve problems more quickly, without placing an excessive burden on the techs in their organization.

Constraints on techs

In order for users to have access to good software tools, techs must do work on a regular basis; this includes being available to fix things when they break. We generally do this work quietly and efficiently, without making a fuss about it, so you might not be aware that any work is being done. Most of us hold down full-time jobs in addition to our volunteer work. Thus, we're making a personal sacrifice for something that we believe in.

Moreover, there are very few volunteer techs. Techs are in great demand all over the world, and very few are interested in volunteer work. There's always far too much volunteer work to be done for the number of techs available, and most of us are at the limit of what we're able to contribute. We have to be quite careful about the way we work, in order to minimize the amount of time it takes. Either tech work will happen in a way that we can handle, or it won't happen at all. If our work on a project starts to take more time than we can give, we may have to leave the project (or some other project).

A single tech may provide services to hundreds or thousands of users. Communication with users is time-consuming. Investigating problems can be extremely time-consuming. In order to make the volume of work manageable, certain practices have developed in the culture of Free Software. These practices place a great deal of responsibility on the user, in order to minimize the amount of time techs spend answering users' queries. Without these practices, queries would be so time-consuming that we would have no time for anything else. Most volunteer techs are steeped in Free Software culture, so the patterns described here are ones you are quite likely to encounter.

How to solve a problem

Most user queries involve a problem that the user could, without assistance, solve (e.g. a misconfiguration caused by not having read the instructions) or at least make considerable progress toward solving. It's essential for techs to weed out these queries, and avoid answering them.

Techs are generally only willing to answer questions about the particular software that they maintain. Don't bother a tech with general questions about how to use your computer, unless she has specifically volunteered to answer those sorts of questions.

Don't expect a tech to do work that you could easily do yourself, or to find information for you that you could easily find yourself. In particular, if you're having difficulty using a program, and you haven't carefully read the instructions for using that program (including all the messages that the program has displayed), don't bother writing to a tech. If you don't find a solution in the program's documentation, look on your organization's web site for a FAQ (a document answering Frequently Asked Questions), and see if your question is answered there. (Your problem may be a known problem, for which there is no solution yet.) If not, try using an Internet search engine; you may find archives of mailing list discussions about exactly the problem you're having, and someone may have posted the solution.

In your search for information, try to form hypotheses about what the problem might be; then test your hypotheses. For example, does this problem always occur, or is it intermittent? Try to simplify what you were doing, and find the simplest possible scenario in which the problem occurs. (This is called a 'test case'.) Even if you don't find the solution right away, you may learn more about the problem, and at least eliminate some possible causes. All this will help a tech spend less time on your problem if you do end up contacting one.

If your investigation reaches a dead end, and you can't find any more information that could help you make progress on your own, it's time to ask a tech for help. At this point, it's crucial that you formulate your question in the right way, and that you send it to the right place.

How to report a problem

Reporting a problem is a skill. If your message wastes the tech's time, she will be less likely to take your next question seriously. Your message should explain precisely and in detail:

• Which software you're using. If the problem involves software you access through a web site, give the full URL of the page on which the problem occurred. If the problem involves a mailing list, say exactly which mailing list it was. (The tech who reads your question may be responsible for many different lists.)
• What you were trying to do, e.g. which button you clicked on when the problem occurred.
• What you expected would happen.
• What happened. Don't say 'It didn't work.' Instead, explain exactly what you observed. (Perhaps it worked, but not in the way you expected.) Include the full text of any error messages that the program displayed; ideally, copy and paste them into your message.
• Precise instructions explaining a simple way to reproduce the problem (your test case).
• What you did to try to correct the problem. Here, it's important to show that you've read the documentation, and looked for information elsewhere.
• What happened as a result of your trying to correct the problem.

The more relevant information you provide, the more quickly a tech will be able to identify the problem. If the tech can't tell what the problem is from reading your description, he may try to reproduce the problem by doing exactly what you did. If your description of what you did is vague, the problem may not occur when the tech tries to reproduce it. In that case, he may reply: 'Works for me.'

Your message must contain a specific question. Examples of good questions:

• The documentation says that this error message means I should do X, but I can't find any information on how to do X. Could you point me in the right direction?
• I've searched everywhere for information on this topic, but I can't find any. Have I missed something?
• It works when I do X, but when I do Y, the problem described above occurs. It seems to me that according to section 3 of the documenation, Y should be acceptable. Have I misunderstood?
• I found some documentation saying that, if this error occurs, it's probably because of a network failure. Is there a network outage at the moment?

In the Subject line of your message, put a very succinct description of the problem. Never leave the Subject line blank. Examples of good Subject lines:

• Frobjar prints 'configuration error' when saving a file
• Glibble rejects messages containing Chinese characters
• '404 Not Found' on foobar.org web site

Use good netiquette when composing your message: don't use HTML format (instructions), don't send large attachments (more than 50K), don't write anything in ALL CAPS. If you're not familiar with netiquette, see the Albion Netiquette page, or the classic Netiquette Guidelines.

Where to send your message

It's important to send your message to the right place. Every organization's web site should provide information about where to send different sorts of queries. Before sending a message to an individual, make sure that that individual is really responsible for maintaining the program you're having trouble with, on the server where you're using it. Don't bother the program's authors with a local problem. Before sending a message to a mailing list, make sure that the list is meant to receive queries on that subject. Each list should provide a description of the sorts of messages that are welcome there, and you can check the archives to see what sorts of things people have posted in the past.

How to interpret the response

The tech's answer will probably be the one that he can give in the least possible amount of time, while still helping you. It's therefore likely to be very terse. Don't interpret this as rudeness; he simply has no alternative.

If the tech feels that you didn't avail yourself of the opportunities for solving the problem on your own, he's likely to reply with a form letter -- or a link to this page. If you've sent your query to the wrong place, the reply will tell you so; it may also tell you where to send your query, but only if the tech who's replying has that information ready to hand.

If you don't get a reply, this could mean that your question was misdirected or poorly formulated, or simply that the people you sent it to have had no time to answer. Don't send the same question a second time. Instead, try investigating some more on your own, or asking your question somewhere else (often there will be more than one appropriate place to send your question).

Sharing what you've learned

If you ask a question on a mailing list, and later on you find a solution (whether or not someone on the list suggested it to you), post the solution on the list, so others can benefit from what you've learned. (Your summary will show up in search results.) If you received several replies to your query, post a summary of the replies. Put Summary: at the beginning of the Subject line.

Requests for general information

Most tech projects have a web site which explains things like the purpose of the project, the current status, and so on. Before emailing a tech to ask for this type of information, look on the web site to see if your question is answered there. When you tell others about the project, send them a link to the web site, rather than a tech's email address.

Complaints and suggestions

You may find that, although a program works as intended, you don't like the way it works. If you send a message to your local techs, complaining that the program is confusing, or doesn't work the way you expected, the reply is likely to be one of the following:

• Are you volunteering to help improve it?
• We know it needs work, but no one has volunteered to do that work. Are you volunteering?

The techs who set up that program did the best they could; telling them that it's not good enough doesn't help them do any better. There's no point in complaining about the way something works unless you have a specific suggestion for improving it. Be sure to explain the purpose of your suggestion; there may already be another way to do what you are trying to do.

If you make a specific suggestion that requires only a trivial amount of work, a tech may offer to implement it. However, keep in mind that what may seem like a trivial change to you may actually require a significant amount of work. Because most volunteer techs are already doing as much work as they can handle, a suggestion that would require significant work is unlikely to be implemented unless you volunteer to implement it yourself. You can always ask -- politely -- whether techs would be willing to implement your suggestion, but understand that you're asking for a favour. Don't expect volunteers to take on extra work just because you think it would be a good idea.

Documentation

Documentation is information about how to use the software, and about what it does in general. Good documentation is essential, but sometimes it is absent or incomplete, because it has to be written by a human being, and no one has found time to write it. If you feel that additional documentation would be helpful, consider volunteering to write it yourself. Similarly, if you feel that the existing documentation could be improved, consider volunteering to revise it. Documentation written by users often addresses users' needs better than documentation written by techs. Techs can often provide the crucial details you would need in order to write a good document, if you are willing to organize the material and write instructions or explanations in a clear style.

Reports

It is often useful to have summary or statistical information about how a program has been used, e.g. statistics on the number of people that have visited a web site. Reports are usually generated by an automated process, but someone has to set up this process. Depending on the information needed and whether programming is required, this could involve a substantial amount of work.

Therefore, when you ask for a report, please specify why you want it. This will enable the tech to determine how important your request is, and perhaps to suggest another way to accomplish what you are trying to do. Keep in mind that you are probably asking for work to be done which nobody has committed to doing; it won't be done unless someone volunteers to do it.

Conclusion

We techs aren't trying to be rude, or to act like prima donnas; the way we communicate with users is simply the only one that allows us to get this work done. Keep in mind that we're volunteers, and that our time is just as valuable as yours. Take responsibility for solving your own problems. Before you ask a question or report a problem, make sure you've exhausted other avenues. Include all the relevant details in your message, ask a specific question, and make sure you send your message to the right place. Don't complain that something isn't good enough unless you have a specific suggestion, or are volunteering to help improve it. And if a tech does solve a problem for you, a thank-you wouldn't go amiss.