Writing Tickets and Technical Documentation

Who reads what you write

Almost everything you write at work is read later, by someone who was not there: the colleague on the next shift, a second-line engineer who picks up your escalation, an auditor checking a change, the user who wants to know what happened to their laptop, and very often yourself, three months from now, with no memory of the details.

That reader has one question: what do I need to know to carry on? Writing well for them is not about style. It is about saving time. A clear note lets the next person start where you stopped instead of repeating your tests. A vague one forces them to call the user again, who then has to explain the problem for the second time and starts to doubt that anyone is working on it.

Writing also helps you think. Typing "Tested: … Result: …" makes it obvious when you have not actually tested anything yet, and documenting your findings is the last step of the troubleshooting method for that reason.

Ticket notes someone else can continue

A ticket has a summary, classification fields and a running log of what was done. That log is made of work notes: dated entries, visible to the IT staff working on the ticket, that record what was observed, tested, changed and decided. Most ticketing tools keep them separate from comments that are sent to the user, so you can be technical and precise in a work note and plain and friendly in a user comment. Check which field you are typing in before you save.

The anatomy of a good note

A useful work note answers five questions, in roughly this order:

1. Symptom: what exactly happens, with the exact error message and since when.
2. Scope: who and what is affected, and just as important, what still works.
3. Tested: each check you did and its result, including the ones that showed nothing. "DNS resolves correctly" is information; it rules something out.
4. Changed: anything you altered, so it can be undone. "Nothing changed" is also worth writing.
5. Next: who has the ticket now, what they are waiting for, and what the user was told.

Before and after

Monday morning at Kestrel Energy. Lucía Romero from billing calls the service desk because the billing application will not log in. Here are two versions of the same work.

INC-20583  billing not working

10:12  user cant login to billing. tried some stuff, didnt work.
       probably network?? sent to network team
10:58  (network) not us
11:30  pls call user

Nothing in this note can be reused. "Tried some stuff" means the next person will try the same stuff. "Probably network" sent the ticket to the wrong team, which spent most of an hour proving a negative. Nobody knows what the user has been told.

INC-20583  Billing app: "Connection to server failed" at login since 09:50

10:12  Amara (SD)
  Symptom  Billing client shows "Connection to server failed (port 8443)"
           at login, since about 09:50.
  Scope    Whole billing team (12 users), per Lucía and 2 other calls.
           Email, intranet and the customer portal work on the same laptops.
  Tested   Lucía's laptop restarted: same error.
           ping bill-app-02.example.com: replies, 4 ms.
           https://bill-app-02.example.com:8443/health in browser: refused.
  Changed  Nothing.
  Next     Server answers ping but refuses the application port, so the
           billing service itself looks down. Functional escalation to
           Billing application team. Lucía told: update before 11:00.
10:31  Joost (Billing)
  billing-api service on bill-app-02 stopped at 09:47 (out of memory,
  see /var/log/billing/api.log). Started it again: health check OK.
  Problem PRB-0244 raised for the memory issue.
10:36  Amara (SD)
  Lucía confirms login works for her and a colleague. Resolved.

The second note is longer, but every line saves somebody time. The scope ("email still works") and the two tests point away from the network and the laptop, so the ticket went to the right team the first time. The billing engineer could start at the server instead of at the beginning.

Resolution notes

The resolution note is the one people read most, because it is what shows up when somebody searches for the same symptom next month. It says what the cause was (or that it is still unknown), what fixed it, and how you verified the fix with the user. "Fixed" is not a resolution note. "Restarted billing-api on bill-app-02 after it stopped (out of memory). Login verified with the user. Cause followed up in PRB-0244" is one. When the cause is a software defect, the developers also need a bug report with steps to reproduce, linked to the ticket; see service desk tickets and bug reports.

Writing habits that help any reader

• Facts first, opinion labeled. "Port 8443 refused" is a fact. "Looks like the service is down" is a conclusion; write it as one, so the reader knows what was observed and what was inferred.
• Exact names. Host names, ticket numbers, file paths and versions, not "the server" or "the new version".
• Unambiguous times and dates. 2026-10-05 cannot be misread; 05/10 is 5 October in the Netherlands and May 10 in the United States. Note the time zone when your readers are in more than one.
• No blame, no jokes about users. Users can often read more of a ticket than you expect, and so can the colleague who made the mistake you are describing. Write what happened, not who was careless.
• Short lines and lists. Readers skim. One test per line is easier to scan than a paragraph.
• Write while you work. Notes written afterward from memory lose the times, the exact messages and the tests that showed nothing.

Kinds of documentation

Tickets record one case. Documentation records what is true or useful for many cases. A common reason documentation fails is that one document tries to do everything at once: teach a beginner, list every option, and explain the design, all in one long page that nobody can use under time pressure.

Four needs, four forms

Diátaxis is a framework for structuring technical documentation, created by Daniele Procida. It identifies four distinct needs a reader can have, each served by a different kind of document: tutorials, how-to guides, technical reference and explanation. Keeping them separate makes each one shorter and easier to find.

• Tutorial: a guided first experience for a newcomer, such as "Your first week on the Kestrel ticket tool". It works if the learner succeeds, not if it covers everything.
• How-to guide: a how-to guide gives the steps to reach one specific goal for a reader who already knows the basics, such as "Add a user to the billing application". It starts from the goal and leaves out background the reader does not need right now.
• Reference: dry, complete and accurate facts: an IP address plan, a list of service accounts, the fields of an API. It is consulted, not read from top to bottom.
• Explanation: why the system is designed the way it is, which options were rejected, and what the trade-offs are. This is the document new team members read on a quiet afternoon.

Operational documents in IT

IT operations has its own names for documents, and most of them are how-to guides with extra metadata:

The fixed sections of an incident report are described under the postmortem template.

Standard operating procedures

A standard operating procedure (SOP) is a written, approved description of how a recurring task is done in an organization, so that everyone does it the same way and the result does not depend on who happens to be on duty. SOPs matter most where mistakes are expensive or invisible: a forgotten step in off-boarding leaves an account active after someone has left.

SOP-0031  Off-boarding: user leaves Kestrel Energy
Owner    Mei Chen (service desk lead) · reviewed 2026-09-15 · next 2027-03-15
Trigger  HR off-boarding request (REQ form "Employee leaves"), at least
         5 working days before the last day
Steps
  [ ] 1. Last working day 17:00: disable the account (do not delete;
         mailbox kept 30 days per retention policy).
  [ ] 2. Revoke MFA devices and active sessions.
  [ ] 3. Remove from all groups; note the groups in the ticket first.
  [ ] 4. Collect laptop and phone; record asset tags in the ticket.
  [ ] 5. Ask the manager who receives the mailbox and shared files.
  [ ] 6. Day 31: delete the account; close the request.
Verify   Sign-in with the account fails; asset register shows "returned".
Escalate Account still in use after step 1? Inform security immediately.

Notice what makes it usable: an owner and review date at the top, a clear trigger, one action per step, a way to verify the result, and what to do when something unexpected happens. The checkboxes are there because the procedure is followed with the ticket open next to it.

Diagrams and network documentation

Some things are easier to understand as a picture: how the customer portal reaches the billing database, which firewall sits between two sites, which switch port a printer is on. Useful infrastructure documentation usually includes:

• A logical diagram: networks, subnets, routing and the main services, for understanding traffic flows.
• A physical diagram or rack plan: which device is where, and which cable goes to which port.
• An address plan: subnets, VLANs, gateways and reserved addresses, as a reference table rather than a picture.
• Baselines: what normal looks like, so "it is slow" can be checked. See Documentation and baselines.

Every diagram needs a title, a date, an owner and a legend. A diagram without a date cannot be trusted, because nobody knows whether it shows the network before or after last year's migration. Where possible, generate inventories and diagrams from the real configuration (the configuration management database, discovery tools or the network automation source files) instead of drawing them by hand; generated documents do not drift.

Docs-as-code

Docs-as-code is the practice of writing documentation with the same tools as code: plain-text files (usually Markdown) in version control, changes proposed and reviewed in a pull request, and automated checks that run on every change. The Write the Docs community describes it in exactly those terms: issue trackers, version control, plain-text markup, code review and automated tests.

Why teams adopt it:

• Documentation changes with the system. When the runbook lives in the same repository as the configuration, one pull request can change both, and a reviewer can ask "where is the doc update?".
• History. Version control shows who changed a step, when and why, and old versions can be restored.
• Checks. Simple scripts can find broken links, missing owners or overdue reviews before anyone relies on a stale page.

A check does not have to be clever. This one looks at a folder of runbooks (created by the example itself) and reports the ones without an owner and the ones whose review date has passed on 1 October 2026:

mkdir -p runbooks
cat > runbooks/portal-503.md <<'EOF'
# Customer portal returns HTTP 503
Owner: Web platform team
Review: 2026-12-01
EOF
cat > runbooks/billing-api-down.md <<'EOF'
# billing-api service stopped
Owner: Billing application team
Review: 2026-08-15
EOF
cat > runbooks/vpn-certificate.md <<'EOF'
# VPN gateway certificate renewal
Review: 2027-01-10
EOF

echo "Missing owner:"
grep -L '^Owner:' runbooks/*.md
echo "Review overdue:"
awk -v today=2026-10-01 '/^Review:/ && $2 < today { print FILENAME " (" $2 ")" }' runbooks/*.md

Missing owner:
runbooks/vpn-certificate.md
Review overdue:
runbooks/billing-api-down.md (2026-08-15)

grep -L lists files that do not contain a match. The awk line compares the dates as text, which works because ISO dates (year-month-day) sort in the same order as time, one more reason to write dates that way. In a pipeline, a check like this would run on every pull request and on a schedule.

Docs-as-code is not the only option. Many service desks keep their knowledge base in the ticketing tool, and a wiki is often the right choice for teams that do not use Git daily. What matters more than the tool are the habits in the next section.

Keeping documentation alive

Documentation decays quietly. A server is renamed, a menu moves, a supplier changes, and the document is now confidently wrong. People who follow wrong instructions twice stop reading documentation altogether. Habits that keep it trustworthy:

• A named owner for every document, a person or a team, not "IT".
• A review date that fits how fast the subject changes, and a review after every relevant change.
• Fix it when you find it. If a step is wrong and you have the rights, correct it now; if not, flag it to the owner. This is the core idea of Knowledge-Centered Service.
• Delete or archive what is no longer true. A smaller set of correct documents beats a large set nobody trusts.
• Test procedures by having someone other than the author follow them during a quiet moment.

Objective 4.1 also covers asset management: inventory lists, the configuration management database (CMDB), asset tags, the procurement life cycle, warranty and licensing, and assigned users. That material is explained in Configuration and Asset Management.