Who is the audience for a trouble ticket update?

August 31, 2011

One of things that commentators brought up in response to my entry on why we don't use a trouble ticketing system is that trouble tickets have multiple uses; for example, they can be used later to look up what you did to solve a problem, and the user can use them to see how their issue is progressing. I expect that this is a common thing to say as a virtue of a ticketing system. However, I don't think that this is as easy as it sounds.

First, let's ask an awkward question: when you write trouble ticket updates, who are you writing the update for? Because these praiseworthy goals are generally in conflict; unless you have very unusual users, you cannot write an update that is simultaneously keeping your fellow sysadmins in the loop, documenting the solution to an ongoing problem, and giving the user useful information. Each of these goals calls for a different sort of writing with different contents.

(If you can resolve the problem in a single update you can at least collapse the first two cases together, but not all problems are amenable to this. And once you have a multi-step diagnosis and fix, well, as I've written earlier lab notebooks are not changelogs and so a series of progress reports are not the same as real documentation of a solution. You can reconstruct the latter from the former, but it is a reconstruction and it takes work; what you really want is to do the reconstruction once and then write it all down neatly.)

Particularly, I think that you need to decide right up front if trouble ticket updates are for you and your fellow sysadmins or if they are for users. If they are for sysadmins they contain deep-dive technical details that may well be opaque to someone who doesn't know your system environment. If the updates are for anyone else, you need to write them so that they can be understood by outsiders (with as much or as little actual technical details as you think your users can stand); this is likely to not include important details that fellow sysadmins need.

(A closely related issue is something that I wrote about back in PrivateTicketing, which is that there are times when you need to have discussions that users should definitely not see. These discussions obviously can't go in a public ticketing system.)

You can resolve all of these issues with a sufficiently complex trouble ticketing system, one where you actually have several different audiences for ticket updates (commentators on PrivateTicketing pointed out ticketing systems that support this in various ways). My personal feeling is that trying to wedge all of these different jobs into a single system is going to create something that's rather ungainly, but seeing as we've never tried to use a trouble ticketing system I have to admit that I have no hard evidence for this.

Sidebar: an example of writing for users versus sysadmins

Consider the user-focused writeup of the incident I described here. As you can imagine, my internal writeup included a great many more details than this (eg, I didn't name the failed backend in the user writeup) and omitted some things (as implicitly known by my fellow sysadmins). It also used more technical terminology, because using technical terminology is generally faster and more precise than more general writing.

Written on 31 August 2011.
« Devirtualization
An interesting debugging experience (another tale from long ago) »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Wed Aug 31 01:25:38 2011
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.