Writing the SLA Document People Will Read

The SLA was eleven pages. Page one was a cover. Pages two to four were definitions. They defined "incident", "request", "business day", "the Service", "the Customer" (that was you, in accounts, with the broken printer) and "best endeavors". The last was defined more carefully than anything else in the document and still meant nothing. The targets table was on page seven. Nobody found it. The document had been approved, signed and uploaded to the intranet, where it enjoyed the rare distinction of being read fewer times than it had pages.

The page that replaced it had eight headings and fit on one side of a sheet. Users read it once, which is all a user ever needs to. The desk kept a copy pinned above the monitor. The manager read the report it produced. Nobody asked what "the Service" meant, because it did not say "the Service". It said "we". This article is part of our SLA Design series. It is about writing that page: what goes on it, in what words, and what you do with it once it exists.

It starts with who reads an SLA and how often, which decides its length. Then it covers the eight headings and what each must say, followed by the language. Next, it covers where the document lives, how to announce it and the annual review. It ends with the external-customer version, which is the one case where a lawyer gets a vote. The one-page template is near the end, filled in for a desk you can rename.

Who Reads the Document, and How Often

Three audiences read an SLA, at three different rates, and the document has to serve all of them without becoming three documents. The user reads it once, usually when something has gone wrong, and wants one thing from it: when will I hear from you. The desk refers to it weekly, in triage and in the awkward conversation, and wants the targets and the exclusions in a form that can be quoted. Management does not read the SLA at all after approving it. Management reads the report it produces, and wants to know whether the desk is keeping its word.

That pattern decides the length. A document read once by its largest audience has to be readable in two minutes by someone whose printer is broken. A document quoted weekly has to be short enough to quote. The eleven-page version was written for a fourth audience, an audit that never came, and it served the other three badly in order to be ready for it.

One page is not a stylistic preference; it is what the readership adds up to. An SLA that cannot fit on a page is either promising too much or defining things it should be saying.

The One-Page Structure

The page has eight headings, in this order, and the order is the user's order, not the desk's. It starts with what we promise, the priority definitions, the targets table and the clock. Then come what we do not promise, how to escalate, how we report and when we review. The first four answer the user's one question. The fifth is honesty. The last three are plumbing, and they are short because plumbing should be. Each heading is one short paragraph or one small table, and the whole page is between three hundred and five hundred words.

The First Half of the Page: Promises, Priorities, Targets, Clock

"What we promise" is three or four sentences in the first person plural, and the first is the one users will remember: "A person will reply to every ticket within the time for its priority, and you will hear from us at least every [interval] until it is resolved, whether or not there is news." Then the warning-before-a-miss promise and the escalation promise. Nothing in the section should need the table to make sense, because many users will stop here.

"Priority definitions" is a four-row table: each row a priority, a one-line definition in terms of how many people and how badly, and two examples. Priority is the rank that sets the targets, and the desk sets it after triage. Say so in one sentence, so the user knows their "urgent" is a suggestion the desk will take seriously and then decide. Writing definitions a small desk can tell apart is the work of Priority Tiers That Are Realistic. On the SLA page, each is one line.

"Targets" is the table everyone turns to: priority down the side; response, resolution and update interval across; and a footnote no longer than two lines. The response target is how soon a human replies; the resolution target is how soon the problem is fixed or the request fulfilled. Every number is in business hours or days, and the word "target" is in the heading. Four rows, three columns. If the table has more cells than that, the twenty-cell matrix is trying to get back in.

"The clock" is four sentences: the business hours, where the holiday calendar is, when the clock starts (when the ticket is logged, by any channel), and what it does and does not pause for. That last sentence has to describe the tool you have, not the tool the template assumed. QuerySolv's documented behavior, for example, is that the clock does not pause on hold, and only non-working hours and holidays are excluded. An SLA written for it says "the clock runs during business hours and stops for holidays". It puts the waiting-on-you promise in words rather than in the clock. A clock sentence that does not match the tool is the first thing the desk will be asked about.

The Second Half of the Page: Exclusions, Escalation, Reporting, Review

"What we do not promise" is the honesty section, and it is five lines at most. It includes the dependency promises in their split form. Examples include: ordered within a day, delivery depends on the supplier; logged with the vendor within four hours, their response time applies after. It includes equipment outside the supported list, requests that are really projects, and major incidents, which switch to their own hourly update. Choosing those lines is the subject of What to Promise and What Never to Promise. On the page, each is one plain sentence that says what the desk will do at the point it loses control.

"How to escalate" is two sentences and a name or a role. "If you think your ticket has the wrong priority or is stuck, reply to it with the word escalate, or call the desk; [role] will review it within [n] business hours." The promise is the review, not the outcome, and the route has to be something a frustrated person can do without reading instructions.

"How we report" is two sentences: what number is published, where, and how often. "Each month we publish the share of tickets that met their targets, and the number of misses by priority, on the IT page." The report is the SLA's proof of life, and promising to publish it is a promise the desk keeps even in a bad month, which is the month it matters. If the ticket system can print the figure, use that rather than a spreadsheet. QuerySolv's reports, for instance, print first-response compliance over seven, thirty or ninety days. That is harder to argue with than a number somebody typed.

"When we review" is one sentence, and it names a month: "We review these targets every [month] against the year's breach reviews and publish any change on this page." That sentence is the difference between an SLA and a monument. A monument is admired, weathered, and never updated, and most SLAs are hard to tell from one.

The Language

Write the page in the second person, to the user, in the plainest words the subject allows. Use "You will hear from us" rather than "the Customer will be notified". Use "we will fix it or tell you why not" rather than "the Service Provider shall use reasonable endeavors to effect resolution". An internal desk is not a party to a contract with its colleagues. It is a group of people making a promise to another group of people in the same building, and the language should sound like it. Every "shall" and "herein" is a small sign to the reader that the page was not written for them, and they will take the hint.

Here is one sentence from the eleven-page version and its replacement. Before: "The Service Provider shall respond to Priority 2 Incidents within four (4) Business Hours of the Incident being logged in the Service Management Tool, subject to the exclusions set out in Schedule B." After: "P2: we reply within four business hours." Same promise. One of them a person can remember while walking to the kitchen.

Three habits keep the tone right. Define nothing you can say: if "business hours" needs defining, say "08:00 to 18:00, Monday to Friday, except the holidays listed here" where it first appears and never again. Use "target", never "guarantee", and never "best endeavors", which is the sound a document makes when it has decided not to promise anything. And write the page for somebody with a broken printer and four minutes, because that is who will read it.

Where the Document Lives

The SLA lives in one place and is linked from three. The one place is beside the scope page, the document that says what the desk supports and what it does not. The two questions a user has are "do you support this" and "how fast". They should be answered one click apart. The scope pillar covers the first page. Put the two in the same place, with the same owner.

The three links put the page in front of a user at the moment they want it. The requester portal, where the user is about to open a ticket and is wondering what will happen. The acknowledgment e-mail, where the user has just opened one and is wondering when they will hear back. Use one line in the receipt, "our response targets are here", with the link. And the IT page on the intranet, for the person who goes looking. Three links, one URL that does not change when the document is revised.

Do not e-mail the document as an attachment, and do not put it in a shared folder with a version number in the filename. Attachments breed. Within a quarter there will be three versions in circulation, and the one with the wrong targets will be pinned to a wall somewhere. One URL, edited in place, with a "last reviewed" line at the bottom, is the whole distribution strategy.

Announcing It

The announcement is short, and it is built so that the user remembers one thing: when they will hear from you. Everything else they can look up. Here is the announcement Dana sent for the Kestrel Payroll desk, three technicians, on the morning the one-page SLA went up:

Subject: What to expect when you contact IT

From Monday, every ticket you send us has a response target.
A person will reply within:
  - thirty minutes if several people cannot work,
  - one business hour if you cannot work,
  - four business hours if something is broken but you can work around it,
  - one business day for everything else.
You will hear from us at least once a day until it is resolved, even
if there is no news.
If you think a ticket is stuck, reply to it with the word "escalate".
Our business hours are 08:00 to 18:00, Monday to Friday.
The full page, with how we decide priority and what we do not promise,
is here: [link]. It is one page.

Dana, IT

Note what the announcement does not do. It does not explain the priority definitions or list the exclusions; they are on the page. It does not use the acronym SLA at all, because nobody in accounts has been waiting for an SLA; they have been waiting for a reply. Send it once, from a person, and then let the acknowledgment e-mail do the reminding. An SLA announced three times is an SLA people suspect; an SLA that turns up in every receipt is a fact of life within a month.

The Annual Review

Once a year, in the month the page names, the desk reads the year's breach reviews, changes one thing on the page, and republishes it with a new "last reviewed" line. The breach reviews are the evidence; the monthly method that produces them is in SLA Breaches and What They Teach. The annual review reads the twelve sheets, finds the one thing they agree on, and changes it.

One change is the discipline, for the same reason as in the monthly review: a page that changes four things a year is a page nobody can quote with confidence. One candidate is a target met nineteen times in twenty all year (tighten it, a little). Another is a target breached a quarter of the time with the same cause (split it, or fix the cause). Other candidates are a priority definition users keep misreading, or a clock sentence that does not match what the tool did. If the sheets say "weather" twelve times, the change is the "last reviewed" line, and that is a good year.

Publish the change in one sentence under the heading, with the old number and the new one. "Reviewed [month]: P3 response target tightened from two business days to one, because we met two days in ninety-six percent of tickets." Users trust a page that shows its working. Nobody will read the old version. Nobody read the old version of the eleven-page one either, for different reasons.

The External-Customer Version

Everything above is for an internal desk, and one section changes when the SLA is part of a contract with a paying customer: all of it, a little. Definitions tighten, because a dispute will turn on what "response" meant, and "a human reply" becomes "a reply from a named support contact, excluding automated acknowledgments". Penalties appear, usually as service credits. These are a share of the fee returned for a month in which a target was missed more than an agreed number of times. Once penalties exist the measurement method has to be in the document too, because it will be checked. The clock gets a paragraph instead of a sentence. And a lawyer reads it, which is correct, and which is the reason the internal version should never have one.

Keep the one-page version anyway, as the summary at the front of the contract or as the page the customer's own staff actually see. The contract is the agreement; the page is the promise, and customers remember the page. What a managed service provider's SLA looks like from the other side of the table belongs to the sourcing pillar.

I have written both kinds, and the internal one is harder. The contract has a lawyer to stop you overpromising. The internal page has only you, and "we will fix anything in two hours" looks very reasonable at 16:00 on a Friday with an empty queue.

A Short War Story: One Page at Meridian Parts

Meridian Parts had the eleven-page SLA, approved two managers ago, and nobody on the desk could say from memory what the P3 resolution target was. Sam, who had run the desk for a year, wrote a one-page version over two afternoons. He kept the same targets where the breach reviews said they were right, split two promises at the vendor, and put the whole thing in "we" and "you". He put it beside the scope page, linked it from the acknowledgment e-mail, and sent a ten-line announcement. In the following month the page received exactly one question, from Priya in dispatch, who read it, read it again, and asked, "Is that all?" Sam said yes. That was the point.

The old document was archived, not deleted, in case the audit ever came. It has not.

The One-Page SLA Template

The template below is filled in for Kestrel Payroll's desk, three technicians and business hours of 08:00 to 18:00. That gives every blank a worked example beside it. Replace the numbers with the ones your breach reviews support, the names with yours, and the examples under each priority with the tickets your users actually send. Keep the eight headings and their order. If it runs over five hundred words, find the sentence that is defining instead of saying, and cut it.

IT SUPPORT: WHAT YOU CAN EXPECT FROM US          Last reviewed: [month]

1. WHAT WE PROMISE
   A person will reply to every ticket within the target for its priority,
   and you will hear from us at least once every business day until it is
   resolved, even if there is no news. If we expect to miss a target we
   will tell you before we miss it, with the reason and a new estimate.

2. HOW WE DECIDE PRIORITY (we set it after looking; tell us if we got it wrong)
   P1  Several people cannot work, or a system everyone uses is down.
       e.g. the payroll run cannot start; nobody can print.
   P2  One person cannot work, or several are badly slowed.
       e.g. your laptop will not start; a team's shared drive is missing.
   P3  Something is broken but there is a way around it for now.
       e.g. one printer down and another nearby; a report runs slowly.
   P4  Questions, changes and requests with no deadline today.
       e.g. an account for next month's starter; a how-do-I question.

3. OUR TARGETS (business hours; see 4)
   Priority   We reply within        We aim to resolve within   Updates at least
   P1         thirty minutes         four business hours        every hour
   P2         one business hour      one business day           twice a day
   P3         four business hours    three business days        daily
   P4         one business day       five business days         daily
   "Resolve" means fixed, or the request done, or a workaround in place with
   a date for the full fix. A reply means a human message, not an automatic one.

4. THE CLOCK
   Business hours are 08:00 to 18:00, Monday to Friday, except the holidays
   on the IT page. The clock starts when your ticket is logged, by any route,
   and only runs during business hours. It does not stop while we wait for
   you; instead, if we have not heard back in three business days, we will
   remind you once and then close the ticket. Your reply reopens it.

5. WHAT WE DO NOT PROMISE
   - Hardware replacement: ordered within one business day of diagnosis;
     delivery depends on stock and the supplier, and we will tell you the date.
   - Vendor support: case logged within four business hours and chased daily;
     the vendor's own response time applies after that.
   - Equipment or software not on the supported list: best effort, no target.
   - Projects (a new branch, bulk accounts, moves): we agree a date instead.
   - Major incidents affecting most people: hourly updates on the IT page
     replace the targets above until it is over.

6. HOW TO ESCALATE
   Reply to your ticket with the word "escalate", or call the desk. Marcus
   (desk lead) or whoever is covering will review it within two business hours.

7. HOW WE REPORT
   Each month we publish, on the IT page, the share of tickets that met
   their targets and the number of misses by priority.

8. WHEN WE REVIEW
   Every October, against the year's monthly breach reviews. Changes are
   noted here with the old and new numbers.

Every number in the template came from somewhere. Thirty minutes is the P1 target because three technicians can always have one free to reply. One business day is the P2 resolution target because the breach reviews said the desk met it nine times in ten. Yours will differ. The headings should not.

Eleven pages, or one. The eleven-page version answered every question an audit might ask and none that a user did. The one-page version answers the user's question in its first sentence. Write the page, put it where the user is, tell them once, and review it when the page says you will. Then let it be boring, which is what a promise looks like while it is being kept.

Frequently Asked Questions