A Guide To Writing Good Bug Reports and Job Requests
The ECS programmers will try to help you with any problems you have regarding the ECS computing facilities. But our job is harder when we don't have enough information to work with.
Before requesting help from us you should at least read the first section of this technical note, which provides advice on how to make a good request. If you follow these guidelines it will be easier for us to help you and means your request can be dealt with quicker.
The remaining sections of the technical note describes the particular system we use in ECS for tracking requests. Some tips that apply specifically to that system are given. It is not essential that you read these sections before requesting help although doing so may avoid problems that occasionally crop up.
We prefer that problem reports or job requests relating to ECS computing systems be sent to the entire support team
rather than to one particular team member. This should be done through our RT (Request Tracker) system by sending an email to email@example.com
(for problem reports) or firstname.lastname@example.org
for general queries or requests (software installation, changing file access permissions, user account issues, etc). Or instead of email you can use the RT self service
The reasons why you should make requests through RT are explained later in this technical note. Although we're happy to talk to you in person, we may still ask that you submit a request through RT.
Writing a Good Bug Report or Job Request
In order to help solve your problems or deal with your requests quickly we need a good bug report or well specified request. If we have to contact you for more information it will take longer to help you.
A good bug report has these things:
- A descriptive subject line
- Steps to reproduce the problem. If we can't replicate it we can't fix it.
- What you expected to see. Don't assume we know how to use the program you are having problems with.
- What you saw instead. We can't read your mind!
- What computer you were using when the problem occurred.
- If you are sending your request from an email address other than your ECS/SMS or MyVUW one, what your ECS/SMS login name and/or student ID is. If we can't identify you it may be much harder to help you.
The computer name may or may not be relevant but telling us what it is allows us
to determine that. If you aren't sure of the name tell us the room number and (for rooms containing more than one computer) where in the room it is (ie: "3rd from left in the 2nd row").
What makes a good job request is harder to categorise. In general, providing more detail is better than less, but too much may make it hard for us to determine exactly what you want us to do. As an example of the level of detail required, if you want some software installed you should tell us: where we can get it; what version you want; what OS you expect to run it on; and any licencing restrictions or costs that you are aware of.
Below are some additional tips that apply to both problem reports and job requests.
It can be useful if you tell us why you need a problem solved or some work done. We may be able to suggest a work-around or an alternative approach. For example, if you describe what you will be doing with some software you want installed we may be able to tell you how to achieve the same result with software already on our systems.
If your request involves a web site, tell us the actual URL rather than assuming we know where it is or will be able to find it based on a less precise description. So instead of just saying "I tried to login to google and ..." you could say "I tried to login to google at https://accounts.google.com/ServiceLogin
You should also give us some idea how urgent your request is so it can be dealt with appropriately (though keep in mind that "A lack of planning on your part does not constitute an emergency on mine"!). If you have a deadline let us know in your initial request rather than a later follow up ("I asked for this a week ago but forgot to say I needed it by tomorrow..."). Please be honest when providing this information. Saying something is urgent simply to get it dealt with sooner is not very polite to others who may have genuinely urgent requests.
Finally, if you send your request from a non-ECS email address make sure you tell us your ECS username and/or student ID. This is most important for problems that don't affect all users. Knowing who you are may also make a difference to when, how or even if we can help you. Unfortunately we can't deal with all requests immediately so staff and graduate students may get priority over undergraduates for problems affecting only one person. On the other hand a problem that affects all students in a large undergraduate class would get higher priority.
A bad example
I tried to see the Google in Firefox, but it didn't work. I need this now.
In the above is "it" Firefox or the google web page? What was "it" supposed to do? Do you really need this now? And who is email@example.com
A good example
Subject: Firefox doesn't display google search page properly on ECS Linux Computers
I visited http://www.google.com in Firefox on the machine imlay.ecs.vuw.ac.nz in CO232. When I visit the page from my home computer running windows I am presented with an option to search for web pages; there are two buttons below the text input box. However, I am unable to see either of these buttons on the ECS computer. This prevents me from running a search, which I need to prepare a presentation for later today.
My ECS login name is kingstlind.
Reasons For Using RT
There are many good reasons why we prefer that requests be submitted through RT. Here are some of them:
- All team members get to see your request and the one who can best (most knowledgeable, least busy, etc) deal with it will do so.
- We can tell if someone is already working on a request and so avoid duplication of effort.
- It helps teams members keep track of what they are working on and to prioritise their work.
- Team members can see what each other is working on and may be able to offer assistance or advice.
- Your request won't get forgotten about or lost in one team member's overflowing inbox or be delayed if a team member is away.
- If a team member is unable to continue working on a request it's much easier for someone else to take over and to see all the previous correspondence.
This doesn't mean you can't come and talk to us in person.
- Queries that can be dealt with quickly are sometimes best handled that way. But please don't be offended if we can't help you right away and we ask you to submit the request via RT.
- If you are intending to submit an RT request it may be a good idea to talk to someone first to ensure that what you are asking for is feasible and/or to determine what information should be included in the request.
- If you have already submitted an RT request, once you know who is working on it it may be easier to talk to them in person rather than communicating solely by email.
More About RT ("The Gory Details")
When a new request is received by RT it will be assigned a "ticket number" and entered into a request database. A copy of it will also be emailed to all members of the ECS technical support team and a "ticket receipt" emailed back to the submitter. In those emails the tag "[ECS #XXXXX]" (where XXXXX is the ticket number) will have been added to the start of the original subject line. Appropriate email headers are also added to (try to) ensure that any follow up emails will be sent back to RT.
Any support team member can take ownership of a ticket, which means that they rather than the whole team receive follow up emails. But team members who don't own a ticket can still see correspondence relating to that ticket in the database and can also make their own contributions. And any team member can add themselves (or any other person) to a ticket as a "watcher" so they receive follow up emails like the owner and original submitter.
Tips For Interacting With RT by Email
Here are some things to keep in mind when using email (rather than the self service
interface) to interact with RT.
- Leave the "[ECS #XXXXX]" tag unaltered in the subject line of any follow up email:
This allows RT to associate the follow up with the right ticket in its database so that all related correspondence can be found easily. It also means that RT can email copies of the follow up to the correct ticket's watchers.
For RT to do this the tag must be left exactly as it was (including the '[' and ']' characters and the "ECS #" prefix).
If the tag is omitted a new ticket will be created in the database and the whole ECS technical support team will be notified. This can result in confusion, especially if the original ticket is now owned (and being dealt with) by one team member.
If the tag is altered the follow up may end up associated with the wrong ticket (and therefore be emailed to the wrong watchers) or be rejected by RT.
- Use your mail program's "reply to sender" function to send follow up email:
Replying to an existing ticket message when writing a follow up guarantees that the RT tag in the subject will be correct (as long as you don't edit it!). It also ensures the follow up will be sent back to RT due to headers that RT adds to all email it sends out.
Using "reply to sender" is preferable to "reply to all" since the latter may result in watchers receiving multiple copies of the follow up - one directly from your email program and one sent by RT.
- Avoid emailing a new request to RT and at the same time to other recipients:
We prefer that you don't do this due to the confusion it can cause.
RT will automatically add the other recipients as watchers of the new ticket so they will all receive two copies of your email . If they reply to the copy they received from RT the "right thing" (more or less) happens. But if they reply to the copy they received directly from you one of two "wrong things" can occur.
If they "reply to sender" RT will not see their reply, so potentially useful information will not be seen by the other ticket watchers (including the ticket owner or members of the technical support team).
If they "reply to all" RT will receive the message but, because there won't be an "[ECS #XXXXX]" tag in the subject, it will create a new ticket. Then we end up with multiple tickets in our database, all related to the same issue, which can cause confusion. It can be especially bad if a request is cc'ed to a mailing list and many of the list recipients reply in this way.
In some cases you may feel that others should know about a request you are making. If so, rather than sending an email consider creating the ticket using the RT self service interface. Then all watchers only get one copy of your message. And the subject and other email headers of the email they receive will be appropriately set to ensure that follow up correspondence gets correctly processed by RT.
- Avoid adding new cc's when following up to an existing ticket.
RT only adds cc'ed addresses as ticket watchers on initial ticket creation. So if you cc a follow up to a new person, unless we notice and manually add them as a ticket watcher, they may not see all subsequent correspondence. If you must do this mention it in the text of your follow up so we can add them as watchers if appropriate.
- Try to keep one problem report or job request per ticket:
The different requests may not be dealt with by the same person. Having them in a single ticket makes them harder for us to manage.
- Think carefully before re-opening an old closed ticket:
Once a problem has been fixed or a job completed we will "close" the ticket. The correspondence remains in the database so we can search for it if we need to, but the closed ticket won't appear in our list of tickets currently needing attention. An email received with the RT tag of a closed ticket will result in that ticket being re-opened and the new email added to it. The email will also be redistributed to ticket watchers in the usual way.
You should never re-open a closed ticket if you are making a new request unrelated (or only slightly related) to that of the original ticket. One reason is that this makes it harder to find correspondence related to the new request since will be associated with a ticket that has a misleading subject. More importantly if the closed ticket had an owner only they will receive a copy of the new request. If they are away your request may sit unseen in their mailbox for a while. Or if they are busy with other work they may not look at the new email carefully (especially if they don't have expertise that area) and so not realise that other teams members won't see and deal with it.
It is less obvious what should happen if a ticket was closed because a problem was thought to be fixed but then it re-occurs. Or if there is a closed ticket relating to some work you requested previously that you need doing again. Should the original ticket be re-opened or a new one created? The answer depends on whether it is better that the follow up be seen by just the person who worked on it last time or the entire support team.
For a follow up relating to a "recent" problem that has just re-occurred, re-opening the ticket is probably the right thing to do. In that case the same person will most likely continue working on it and re-opening the ticket ensures that all related information is in one place. The difficulty is deciding on the correct definition of "recent". If the original problem was too long ago what looks to you like a re-occurrence may actually be a different problem. Or the person who handled it last time may not be the best one to deal with it now.
It is rarely correct to re-open a closed ticket for a job request that you want repeated. Even if the earlier request was completed "recently" don't assume that the person who helped that time is the only one able to do so now (even if they "always" have previously). The entire team should see your new request so we are better able to share our workload.
If there is any doubt over whether you should re-open a closed ticket, don't! Create a new ticket instead. It would be helpful to tell us the original ticket number (or if you don't know it, any details that will help us find it in the database) so we can review what actions were taken the last time. If we think a new ticket shouldn't have been created we can re-open the original ourselves and merge the new one in to it.
- Don't include large attachments in requests:
Requests remain in the RT database forever and we don't need/want it clogged up with large attachments. A better alternative would be to leave a copy of the attachment(s) in your home folder on one of our servers and tell us the location. If we believe it would be better for a copy of the attachment to be permanently stored in our database we can attach it ourselves.
- Stop and think about what you are adding into the RT discussion; before pressing Send:
Along similar lines to the consideration of placing large attachments into the RT system, is a consideration of what you, often just one participant in a discussion with the Technical Staff, are placing back into the RT system in the body of your emails.
Try to remember (or even visit the SelfService interface to see) that RT keeps a copy of the full body of all the email correspondence, which means that if you simply reply to an email without trimming the content, the RT system is now storing everything twice, and then, if another correspondent replies to your reply, the RT system is now storing everything three times.
Many email clients no longer bother to show you the old message content that you, unknowingly, will be sending back, so try and check, and in most cases, simply delete any old content. In some cases, say where you've been asked a number of questions, then trim the old content as much as possible and insert your answer after each question.
Similarly, just because your email client acts like a colouring book, remember that not everyone reading your email will have chosen to use the same client as you, so don't refer to coloured sections of your email, indeed, it's probably better not to use colour at all.