Resolution Notes Worth Reading Later

Monday, 08:40. Jonas has a ticket from the drawing office. The connection to the office network drops every twenty minutes for anyone working from home, and it started on Friday. He does what any sensible technician does first and searches the ticket history for "connection drops". Six closed tickets come back, spread over fourteen months, three different users, two different technicians. The notes read, in full: "fixed", "user ok now", "see previous", "reinstalled", "n/a" and "resolved per call". He opens the one that says "see previous". It refers to the one that says "n/a".

There are six tickets, perhaps three days of somebody's work. The sum of what they tell Jonas is that the problem has happened before and was, at some point, made to stop. He starts from the beginning. So did the technician before him, and the one before that, each of whom closed their ticket with a word. At the moment of closing they knew what they had done and could not imagine anybody needing to be told.

A resolution note is the short written record made at the close. It records what the problem was, what caused it, what was done about it, and how you knew it worked. Four lines, in that order, written for a stranger. This article is part of our Closing Tickets Properly series, which treats the note as one of the four parts of a proper close. This is the article about writing one that is still useful when someone finds it next year.

It covers who the stranger is and why you are writing for them. Then come the four lines, one at a time, with what each must contain and what it must not. A table puts bad notes beside the good notes they should have been. We cover where the note lives in the ticket and who can see it, then writing so that a search will find it. Next comes when a note should become a knowledge article, followed by a note skeleton you can paste into every close.

The Stranger Who Will Read This

Every resolution note has one reader, and it is not you. It is a competent stranger: someone who knows the trade but was not there. They have this ticket open because they searched for something and this came up. They need to know in under a minute whether it is the same problem and what fixed it. Sometimes the stranger is a colleague. Sometimes it is a reviewer sampling closed tickets. Most often it is you, in eleven months, having forgotten everything. That is the case people find hardest to believe and the one that happens most.

The stranger reads the note instead of the history, and that is the point of it. A ticket history is the whole conversation. It includes the first message, the questions, the three things that did not work, the reply from the user that arrived during lunch. It is complete and it is useless, in the way a transcript of a meeting is useless to someone who wants to know what was decided. The note is the decision. A ticket history does not summarise itself, and nobody who was in the conversation thinks it needs to.

The test of a note is one question: could a competent stranger repeat the fix from this, without asking anyone? "Fixed" fails the test. "Reinstalled" fails it. "Cleared the saved network profile and rejoined with the current key" passes, and it took twelve seconds more. Everything in this article is a way of passing that test in about ninety seconds per ticket. That is roughly what it costs to not pass it, multiplied by every future stranger.

The Four Lines

A note has four lines, in a fixed order: symptom, cause, fix, verification. The order is the order in which the stranger needs them. Is this my problem? That is the symptom. Why did it happen? That is the cause. What do I do? That is the fix. How will I know it worked? That is the verification. A note that has all four in that order can be read in fifteen seconds and acted on without opening anything else.

One line each is the target, and a line here means a sentence or two, not a paragraph. The discipline is in choosing what to leave out. The three things you tried that did not work go in the history, where they already are. There is an exception: if one of them is a trap the next person will also fall into, it earns a clause. The note is the shortest honest account of the ticket. If it is longer than the first message of the ticket, something has gone wrong with it.

The four lines also keep you honest about what you know. Most bad notes are not lazy; they are the result of not having a cause and not wanting to write that down. The structure gives you a place to say "cause not found" and move on to the fix that worked anyway. That is a far more useful note than one that implies a cause by omitting it. A line left blank in the structure is information. A note with no structure hides what is missing.

Symptom: What the User Saw

The symptom line says what was observed, by whom, and from where, in words that match what a stranger would search for. It is not the diagnosis; that comes next. "Laptop would not join the wireless network in meeting room 2; 'cannot connect to this network' with the correct password; other laptops in the room connected." Three facts: the thing that failed, the exact message, the thing that worked. The exact message matters most, because the exact message is what the next person will type into the search box.

Write what the user saw, not what they asked for. Take a ticket that arrives as "I need a new laptop". It turns out to be "laptop takes nine minutes to start because of a full disk". Its symptom line is about the nine minutes, not the laptop. The request was the user's guess at a fix. The symptom is what the ticket was really about. And it is what the category should say too, which is the argument in Categorize at Close, Not Just at Open.

Quote error text exactly, including the spelling, the code and the punctuation, inside quotation marks. Paraphrased errors cannot be searched for. "Some kind of certificate error" is a memory. The text "the security certificate for this site is not trusted" is a string that the next ticket will contain word for word. If there was a number, keep the number. Nobody has ever regretted writing down an error code. The regret runs the other way.

Cause: The Line Most Notes Skip

The cause line says why the symptom happened, as far as you know, and how far that is. "The saved network profile held the pre-shared key from before the key change in the spring." That is a cause. "Wireless issue" is not a cause; it is the symptom restated with less detail. A cause is a thing that, had it been different, would have made the symptom not happen. And the best test of whether you have one is whether you can say what the next person should check first.

Say when you do not know. "Cause not found; the crash log pointed at the display driver and updating it stopped the crash, but the driver had not changed recently" is an honest cause line. It is a useful one, because the next stranger knows where you looked and how sure you were. A note that skips the cause line implies a cause existed and was too obvious to write. The stranger will assume you knew. You did not, and now neither of you does.

The restart deserves its own sentence, because it is the oldest fix in the trade and the least informative. Restarting something and watching the symptom go away tells you that the symptom was in the running state of that thing and not in its configuration. That is a real finding. It tells you nothing about what put it in that state. Write "cause not found; restart cleared it" rather than leaving the cause line out. That way, the third occurrence can be recognised as the third occurrence. A fault that is restarted away three times is not three tickets. It is one problem with three receipts.

Separate the cause from the trigger where they differ. The trigger is what happened just before: the user opened a large file, a scheduled task ran, the building's power blinked. The cause is why that led to the symptom. "Trigger: the monthly backup window started at 01:00. Cause: the backup job restarts the licence service, which drops every connected session." The trigger tells the next person when to look; the cause tells them what to fix. Most repeating faults have a visible trigger and a hidden cause. And the trigger is what the note usually records, which is why the fault keeps repeating.

Fix: Steps a Stranger Can Repeat

The fix line says what was changed, from what to what, and where. "Removed the saved network profile for office-wifi on the laptop; rejoined using the current key from the password store; set the profile to connect automatically." That is a fix a stranger can do. "Fixed wifi" is a fix only the person who did it can do, and only until they forget. The question to answer is not "what did I do" in the sense of effort. It is "what is different now", which is shorter and more useful.

Name the thing. Name the machine in the form your desk uses. Name the server as a hostname such as fileserver2.example.com. Name the setting by the words on screen, and name the account. "Changed a setting" is the fix line equivalent of "fixed". Where a path or a menu matters, write the path. Where a value changed, write the old value and the new one, because the next person may need to put it back. A note that records the new value without the old one has recorded half a change.

Include the thing you tried first that did not work, in one clause, only if the next person will try it too. "Reinstalling the drawing software did not help; the display driver update did" saves the next technician the forty minutes of the reinstall. "Tried several things" saves nobody anything. The history has the full list; the note has the one trap worth flagging. If there were no traps, the fix line is one sentence, and that is the right length.

If the fix was a workaround rather than a repair, say so in those words. "Workaround: restarted the licence service; the underlying cause (the backup job) is still in place and has been raised as ticket 48213." A workaround recorded as a fix tells the next stranger the problem is solved. It is not solved. It is scheduled. Known errors and the workarounds that keep them tolerable have their own discipline, which lives in Known Errors and Workarounds. The note's job is only to be honest about which kind of fix this was.

Verification: How You Knew

The verification line says what test showed the fix worked, who ran it, and from where. "User connected in meeting room 2 and loaded the intranet home page; confirmed by reply at 14:10." It is the difference between "should work" and "worked", and that difference is the difference between a close and a reopen. A note without a verification line is a prediction. Predictions are fine. They go in a different column.

The test should match the symptom. If the symptom was a crash on files over a certain size, the verification is opening a file over that size, not opening the software. If the symptom was a connection dropping every twenty minutes, the verification is a connection that stayed up for more than twenty minutes. In that case, the verification took at least twenty minutes, and the note should say when it started and when it ended. A verification that tests something easier than the symptom is a verification of something else.

Record who verified. "Technician tested from the desk" and "user confirmed from their own machine" are both verifications. The second is stronger, because the user's machine is where the symptom lived. When the user has not yet confirmed, the line says so and names the date you asked for: "Awaiting user confirmation, requested by Friday." The note can be finished later. The honest version of unfinished is better than the finished version of untrue. How to get the confirmation without chasing for a month is the subject of User Confirmation Without Chasing Forever.

Good and Bad Notes Side by Side

The table below takes four notes of the kind Jonas found and sets beside each one the note it should have been. Read the middle column first; it names the thing the bad note left out, and it is nearly always the cause or the verification. The good notes are longer, and none of them is more than four lines. None of them took more than two minutes to write while the fix was fresh.

Notice what the good notes do not contain. No account of the technician's morning, no apology, no "the user was very patient", no list of everything tried. They contain four facts and the names of the things involved. A good note is dull in a specific way. It is dull the way a recipe is dull, because it exists to be followed rather than enjoyed.

Where the Note Lives

The note lives in the ticket, as the last entry before the status changes. And it is written for the desk rather than the user. In most tools that means an internal note: a comment on the ticket that the requester never sees. That is distinct from a reply, which is mailed to them. In most tools an internal note is never mailed. In those tools, the technical version with hostnames, settings and the thing you suspect but could not prove can go there in full. Check yours once, because a note that turns out to be public is a surprise for everyone. The requester gets the same facts in their own words, in the closing reply. That is a different document for a different reader and is the subject of Avoiding the Silent Close.

Some tools have a dedicated solution field. And some make it mandatory, which is how a desk ends up with a thousand tickets whose solution field contains a full stop. A mandatory field produces a filled field, not a useful one. If your tool has a solution field, put the four lines in it. If it has only notes, put them in the last internal note. In that case, begin it with the word RESOLUTION so a reader scrolling the history can find it. What matters is that every technician puts the note in the same place, so the stranger knows where to look.

Write the note before the reply and before the status change, not after. Before the reply, because the reply is the note translated for the user and is quick to write once the note exists. Write it before the status change because once a ticket is Resolved it leaves the working view. A note that was going to be written later is a note that was not written. The order confirm, note, tell, categorise, then Resolved is the whole of What a Proper Close Looks Like. And the note is the step in the middle that the other steps depend on.

Writing for Search

A note is found by search or not at all, so the words in it are the words the next person will type. Think of the stranger at the search box with the new ticket open beside them. They will type the error message, the name of the device, the name of the software, or the symptom in the user's words. Every one of those should appear in the note, spelled the way it appears on screen. Most tools search ticket text and knowledge articles together, and the search is only as good as the words that were written down.

Include the synonyms people actually use. The user calls it "the wifi"; the configuration calls it the wireless profile; the error says "network". Put all three in the symptom line and the note will be found whichever one the next person searches for. Name the device the way the label on it reads and the way the inventory spells it, if they differ, and they usually do. A note that calls the printer "the big one by the door" is accurate and unsearchable.

Make the first line the title. The tool may show only the first line of a note in a list or a search result. In that case, that line should say what the note is about: "RESOLUTION: wifi join failure in meeting room 2, stale saved key." A reader scanning twenty results can pick the right one from the first line without opening any of them. A first line that reads "Hi, so after looking at this" has told the reader what time of day it was written.

From Note to Knowledge Article

A note becomes a knowledge article when the same cause appears for the third time. The first note is a record; the second is a coincidence. The third is a pattern. A pattern deserves one article that the next five tickets can be closed with a link to, instead of five notes that each rediscover it. The note is the raw material. A good one is already most of the article. The symptom is the title, the cause is the explanation, and the fix is the steps. And the verification is the "how to check" line at the end.

Keep the article honest about its audience. A knowledge article written for technicians can hold hostnames and settings. One written for users holds the steps they can take and the point at which they should stop and raise a ticket. Most knowledge bases can mark an article as a draft, as visible to agents only, or as published to users. The right default for a new article is agents only: the note becomes a technician article first. It becomes a user article only when someone has rewritten it for users. Whatever tool you use, make the first version internal. A user article promoted too early is a user article with a hostname in it.

The third-time rule also feeds problem management, which is the practice of fixing the cause instead of the fault. That depends entirely on notes that record causes. A desk whose notes say "fixed" cannot find its repeat tickets, because every repeat looks like a new fault. The method for finding them, and what to do when you have, is in Finding the Repeat Tickets. It starts with reading cause lines, which is to say it starts here.

A Short War Story: The Search That Found Nothing at Redbrook Engineering

Redbrook Engineering's drawing office lost its connection to the licence server for its design software on the first working day of most months, usually around 09:00. Over a year and a half the desk closed six tickets about it. The notes read "restarted service", "ok now", "same as before" and three variants of "fixed". When Marta inherited the seventh occurrence she searched the history, found nothing she could use, and spent two days on it. During that time eight engineers worked from printouts for a morning. The drawing office manager estimated the cost at a lost day of design time. The cause, when she found it, was a monthly backup job that restarted the licence service at 01:00 on the first of the month. After that, the service came up before the network stack was ready and refused every session until it was restarted by hand. She wrote a note with the symptom, the cause, the ten-minute workaround and the test that confirmed it. She raised a separate ticket to move the backup window. The eighth occurrence, three months later, was fixed in ten minutes by a technician who had never seen the problem, from her note. The backup window was moved the month after, and there was no ninth. The six earlier tickets had cost about half a day each, and the note that made the seventh the last one took four minutes.

The Resolution Note Skeleton

Paste the skeleton into the internal note or solution field at every close and fill the four lines. It is deliberately short; a skeleton that asks for twelve fields produces twelve fields containing "n/a". The optional lines at the bottom are for the cases they name and are left out otherwise. Save it as a predefined reply or a text snippet so that inserting it costs one click. That is the only way a skeleton gets used at 16:50.

RESOLUTION: ________________________________________________
  (one line: the symptom and the cause, for search results)

SYMPTOM
  What was observed: ______________________________________
  Exact error text, if any: "______________________________"
  Where / which device or account: _________________________

CAUSE
  Why it happened: ________________________________________
  If unknown: "Cause not found." What was ruled out: ________
  Trigger, if different from the cause: _____________________

FIX
  What was changed, from what to what, where: ______________
  ________________________________________________________
  Tried first, did not help (one clause, only if a trap): ____
  [ ] This is a repair      [ ] This is a workaround; cause raised as ticket ______

VERIFICATION
  Test run: ______________________________________________
  By whom, from where: ___________________________________
  [ ] User confirmed on ______    [ ] Awaiting confirmation, asked for by ______

OPTIONAL
  Repeat? Earlier tickets: ______  ______   [ ] Raised for problem review
  Knowledge article: [ ] exists: ______   [ ] written   [ ] not needed

Two rules for using it. First, fill the cause line even when the answer is "not found". The line exists to make not knowing visible, and a blank line is the one thing it must never be. Second, write the first line last, after the other four, because it is the summary. You cannot summarise what you have not yet written. The skeleton is the same four questions the stranger will ask, in the order they will ask them. Answer them once, now, and nobody has to ask.

Jonas, on his Monday, eventually found what caused the connection drops. A power-saving setting on the home-worker laptops turned off the network adapter after twenty minutes without keyboard input. Three previous technicians had probably also found it, given that "reinstalled" and "resolved per call" both went away for a while. He wrote a note with four lines and a first line a search would find. The next time it happened, someone else fixed it in six minutes and never knew his name. That is the correct relationship between a stranger and a note.

Frequently Asked Questions