What Must Never Be in the User Document: The Leak Test

Wednesday, 14:20, at Oakmoor College. A ticket arrives from a second-year student, and it is polite. "Hi, not sure if this is meant to be there, but the printing guide on the portal has the print server's admin page address in it. It has the name of the admin account, and it says the password is on the whiteboard in the IT office. Thought you'd want to know." Isla, who runs the desk, opens the article. "Printing from the computer labs" was derived from the runbook seven months ago, in a hurry, by softening the first three steps and leaving the rest. Step six still reads: "If the printer still does not appear, sign in to the print server's management page at the internal address using the print-admin account. The password is on the desk's whiteboard." The portal is reachable by every student, every visiting lecturer and anyone who has ever been given a guest login. Nine hundred people could have read step six. One did, and was kind enough to say so.

A leak is anything in a published document that should only have been visible to the desk. It might be an address, a name, a credential, or a step that bypasses a control. Or it might be a fact about the inside of the network that helps someone who should not be helped. Leaks happen almost entirely at one moment, when the user guide is derived from the runbook and something that belonged to the runbook comes along for the ride. They are prevented almost entirely by one habit. That is to read the guide before publishing as the least trusted person who can reach it. This article is part of our Technician Docs vs User Docs series. This article is the list of what must never cross from the technician's document to the user's, with the test to run before anything is published.

It covers why "published" means "public", admin paths and console addresses, and credentials, service accounts and where the password lives. Next come bypasses and the workaround that skips a control, internal names, and the step that only works with elevated rights. Then come screenshots, which leak as easily as text, the leak test itself, and what to do when you find a leak already published. A short war story and the leak checklist to copy come last, in that order.

Published Means Public

A published article is visible to everyone who can reach the portal. And "everyone who can reach the portal" is always a larger group than the desk pictures when it clicks publish. Staff, yes. That also includes contractors with a login, students, tenants, patients, and agency workers. It includes the supplier's engineer who was given access for a project and never removed, and the former employee whose account was disabled but who kept a printout. It includes the search engine that found the page because the portal was not quite as private as the firewall diagram suggested. Write for the least trusted person on that list. If the sentence would worry you in their hands, it does not go in.

Published also means copied. Users screenshot articles and paste them into chat. Managers print them for the noticeboard. Helpful colleagues forward them to a friend at another company who "has the same printer". Once an article is published, the desk has no control over where it goes. A leak in a published article has to be treated as a leak to the world, because the desk cannot prove it was not. The time between publishing and the first copy is short, and the time between the first copy and the last is forever.

None of this is an argument against publishing. User guides deflect tickets, help people at the moment they are stuck, and are the visible face of a desk that knows what it is doing. It is an argument for a gate between the agents-only draft and the public article, and for the gate to be a test rather than a feeling. If you run QuerySolv, the habit already exists on every ticket, where an internal note and a public reply are different things. The leak test is the same habit applied to the moment an article's visibility changes from agents to everyone.

Admin Paths and Console Addresses

The first thing that leaks is the address of something only the desk should reach. That could be the print server's management page, the storage console, the wireless controller, the remote-access gateway, or the address of the directory's administration tool. The runbook needs these, because the technician must get to them. The guide must not have them, because the user cannot use them and someone else can. An address alone is not a password, but it is the door. And a published list of doors is a gift to anyone who was going to look for them.

The address leaks in three forms, and the first two are easy to miss. The obvious form is the address written out. The second is the address inside a link, where the visible words say "the management page" and the link underneath points somewhere internal. Read every link's target, not its text. The third is the address in a screenshot's browser bar, which is covered below. The guide replaces all three with nothing, because the user's version of "sign in to the management page" is "raise a ticket". What the desk does after the ticket is the desk's business.

Credentials, Service Accounts and Where the Password Lives

Credentials never appear in any document, including the runbook, and the runbook is where this rule is usually first broken. A runbook says which account to use and where the password is kept, in the desk's password store, under a named entry. It does not contain the password. A guide says neither. The account's name is itself a leak, because an account name is half of a credential and the half that is hardest to change. "Use the print-admin account" tells the reader there is an account called print-admin with rights over printing, which is more than they knew a sentence ago.

Where the password is kept is also a leak, and a subtle one. "The password is on the whiteboard" is a sentence that tells every reader where to look. "The password is in the desk's password store" is better and still does not belong in a user document. The user has no business knowing the desk has a password store, let alone which one. The guide's reader needs their own account and nothing else. Any sentence in a guide that mentions another account, any account, is a sentence to delete. The same rule, applied to what a technician types into a ticket that a requester can read, is in What Never to Write in a Ticket. The article and the ticket leak the same way and are cleaned the same way.

Shared accounts for users are the hard case. Some organisations have a generic sign-in for a kiosk, a training room or a lab. And the user guide for that room is tempting to write with the credentials in it, because the user genuinely needs them. Do not. The guide says "sign in with the lab account; the details are on the card in the room". The card is a thing that can be changed, removed and counted, which a published page cannot. A credential on a published page has been published, and no amount of "it is only the training room" makes it otherwise.

Bypasses and the Workaround That Skips a Control

A bypass is any step that gets round a control rather than through it. Examples are disabling the security prompt, adding an exception to the content filter, or connecting to the guest network instead. Others are using the other printer that is not on the restricted list or signing in with a colleague's account. Technicians know bypasses because technicians use them, deliberately and briefly, to diagnose a problem. A runbook may legitimately say "temporarily disable the proxy to confirm the fault is the proxy, then re-enable it". The guide may never say anything of the kind, because a bypass published to users is a control that no longer exists.

Bypasses leak in the voice of helpfulness. The technician deriving the guide knows that the quickest way past the problem is the workaround, wants the user back at work, and writes the workaround down. The user follows it, and it works. And it keeps working, because the workaround was never undone, and now the content filter has a published instruction for turning it off. The control's owner finds out at the audit. The question to ask of every guide step is "what does this step get round?", and if the answer is anything, the step is out. A user guide that teaches users how to avoid the desk's controls is not self-service. It is a policy change nobody approved.

Workarounds for known errors are the legitimate cousin, and the distinction is worth stating. A workaround that restores a symptom without touching a control, such as "sign out and sign in again", is fine in a guide. A workaround that restores a symptom by removing a protection is a bypass, however temporary the runbook says it is. Temporary, in a published document, means permanent, because the document does not know when to stop.

Internal Names

Server names, network ranges, share paths, and the names of internal applications all belong in the runbook. So do project code names, supplier account numbers and the names of the people on the on-call rota. None belongs in the guide. Each one tells an outside reader something about the inside: how the network is laid out, what is running on it, who to impersonate on the phone. Individually they look harmless. "The file server is called FS02" is not a secret in any formal sense. Collected across forty published guides, the names draw a map of the organisation's systems that nobody would have agreed to publish as a map.

People's names are the internal names most often published by accident and most often defended. "If this does not work, contact Jo in IT" feels friendly and is three leaks. It names a person and tells readers that person has the power to fix the thing. It routes work around the queue to a mailbox. The guide says "raise a ticket". The desk's rota decides who Jo is this week. A guide that names a technician will still be naming them two years after they leave, which the people who phone them will discover before the desk does.

Replace every internal name with the user's name for the thing. "The drive you open for drawings" rather than the share path. Use "the timesheet system" rather than the application's internal name, unless the internal name is what the user sees on their screen. In that case it is already the user's name and may stay. The test is whether the name tells the user anything they need, and whether it tells an outsider anything they want. A name that does the first and not the second stays; any other name goes.

The Step That Only Works With Elevated Rights

The elevated-rights step is not a leak in the security sense. And it is in this article because it fails in the same place and is caught by the same test. It is a step that the technician did with administrative rights and that the guide gives to a user who has none. Examples are opening the service list and restarting the service, changing a setting in a protected part of the system, or installing the driver. Another is clearing a queue that belongs to everyone. The user tries it. The system says "access denied", or worse, says nothing and silently does not do it. The user raises a ticket that begins "I followed the guide and it said access denied". That is a ticket that starts with a complaint about the guide and takes longer than one that starts with the problem.

These steps leak because they look safe to the person deriving the guide, who has had administrative rights for so long that they no longer notice using them. The derivation method in Writing the User Guide From the Runbook asks of every step whether a user can do it with their own account. The honest way to answer is not to think about it but to try it, on an ordinary account, on an ordinary machine. The technician who tests the guide on their own machine has tested nothing. Their machine says yes to everything.

The elevated-rights step also leaks information when it fails, which is why it belongs with the others. "Open the service manager and restart the spooler" tells the user that there is a service manager. It tells them that the spooler is a service and that restarting it fixes the problem. And a user who has been told that will, next time, find a way to do it, with a colleague's account or a borrowed laptop or a search engine. The guide has taught a bypass without meaning to. Steps past the wall stay past the wall, and the guide's hand-off line is "raise a ticket", not "here is what we would do".

Screenshots Leak Too

A screenshot is text that nobody reads before publishing, and it leaks everything above. The browser bar shows the console's address. The title bar shows the server's name. The taskbar shows the technician's name, the time, and three other applications. The background window shows a ticket with another user's name on it, or a password store, or the rota. The screen was captured on a technician's machine during a technician's session. And the technician's session is full of things that are not for users, every one of which is now a picture on the portal.

Crop every screenshot to the part of the screen the step is about. Take it on an ordinary account on an ordinary machine, using the same account the guide was tested on. Read the image after cropping, slowly, as a stranger: every word visible in it is published, including the words in the corners. Where the step is "click the button in the top right", a picture of the top right is the whole picture. The craft of a screenshot that helps rather than decorates, with the cropping and marking rules, is in Screenshots That Help, and the Ones That Do Not. The leak test adds only that the picture is read for leaks exactly as the text is, before publishing, by someone who did not take it.

The Leak Test Before Publishing

The leak test is a read of the whole guide, text, links and images, by someone who did not write it. They read in the role of the least trusted person who can reach the portal, asking four questions of every line. Does this tell me where something is that I should not be able to reach? Does this tell me an account name, a password, or where a password is kept? Does this get me round a control? Does this name a system, a network or a person I had no business knowing about? Any line that earns a yes is removed or rewritten. And the test is run again from the top, because the rewrite is a new line.

The second reader is the whole test. The writer cannot do it, for the same reason the technician cannot test rights on their own machine. The writer knows what every line means and cannot read it as someone who does not. The second reader need not be senior. A colleague on the desk, reading with the four questions on a card beside them, finds nearly everything. A second reader from outside the desk, who does not know the server names, finds the rest. A line that means nothing to them is a line that is safe, and a line that makes them curious is a line that is not.

The leak test is the last gate before the article's visibility changes, and it belongs inside the desk's existing review rather than beside it. The light review that takes an article from an agents-only draft to a published one, and the question of which drafts should stay internal forever, is in From Draft to Published: The Light Review. The article review checklist that checks a guide for everything else, from title to last step, is in The Article Review Checklist Before Publishing. The leak test is the security column on both, and it is the one column that is never skipped because the article is short. The shortest guide at Oakmoor was the one with step six in it.

When You Find One Already Published

When a leak is found in a published article, the first action is to take the article down, before deciding how bad it is. The time spent deciding is time the article stays up. Unpublish it, or set it back to agents only, or replace its body with "this article is being updated", whichever the tool does in one step. Then assess. What leaked, for how long, to whom could the portal be reached by, and does anything in it need to be changed as well as removed? An address can be removed. An account name that has been visible for seven months may need the account renamed. A password location may need the password rotated. A bypass that users have been following may need the control checked, because it may already be off.

Record it as a ticket, with the article's number, what was found, when it was published, when it was removed, and what was changed in consequence. The record is not for blame. The person who derived the guide in a hurry seven months ago was doing the right thing badly, which is the ordinary condition of a busy desk. The record is so that the leak test gets added to the review if it was not there. It is so that the other guides derived in the same hurry get read the same week. And it is so that if the leak ever matters, the organisation can say what it knew and when. Then thank the student. A leak reported by a polite user is the cheapest way a leak has ever been found. And a desk that is grateful will be told next time too.

A Short War Story: The Scanner Guide at Bellweather Logistics

Bellweather Logistics published a guide called "Setting up a warehouse scanner" for shift supervisors at its four depots. The guide was meant to let them get a new handheld onto the wireless network without waiting for the desk. It had been derived from the runbook by a technician called Priya in the week she was also covering the phones. So step four still read "join the warehouse wireless network using the key from the runbook", followed by the key. Step seven still gave the address of the wireless controller's admin page. The portal was reachable by every driver, agency picker and visiting haulier with a depot login, which was several hundred people a quarter. The guide was live for fourteen months before a security review found it by searching the portal for the word "key". Nobody could say who had read it, so the key was treated as public. It was rotated across all four depots in one weekend, which meant re-keying three hundred and ten scanners by hand. Two depots ran a shift on paper while it was done, and the admin page was moved and its account renamed. The weekend cost the desk and two supervisors about ninety hours. The guide, when republished, had three steps and a hand-off line reading "then raise a ticket with the scanner's label number and the desk will connect it". Every published article is read by the least trusted person who can reach it, and the desk had never once asked who that was.

The Leak Checklist

The checklist below is the template for this article: the leak test as a card. The second reader works through it before an article's visibility changes from agents to everyone, and again whenever a published article is edited. Keep the completed card with the article's draft, not on the portal. The section headed "if found after publishing" is the one to read calmly, in order. The natural response to finding a leak is to argue about how bad it is, and the first step is to take it down.

LEAK CHECKLIST — BEFORE AN ARTICLE IS PUBLISHED
Article: G-____  Title: _____________________________________________
Derived from runbook: RB-____   Written by: ________   Date: ________
Second reader (not the writer): ______________   Read as: the least trusted
person who can reach the portal. List who that includes: ______________

TEXT (every line, every list item, every caption)
  [ ] No address of a console, management page, gateway or admin tool
  [ ] No link whose target is an internal address (check the target, not the words)
  [ ] No account name of any kind other than "your own account"
  [ ] No password, and no sentence saying where a password is kept
  [ ] No shared or room credentials (point to the card in the room instead)
  [ ] No step that disables, skips, excepts or avoids a control
  [ ] No "use the other network / printer / login" workaround
  [ ] No server name, share path, network range or application code name
      unless it is what the user sees on their own screen
  [ ] No supplier account number or fault reference
  [ ] No person's name, phone number, mailbox or rota
  [ ] No step that needs rights the user does not have (tried on an
      ordinary account, on an ordinary machine, by: ________)
  [ ] No cause, history or "this happens because"

IMAGES (each one, after cropping)
  [ ] Taken on an ordinary account on an ordinary machine
  [ ] Cropped to the part of the screen the step is about
  [ ] No browser bar, title bar, taskbar or background window visible
  [ ] No other user's name, ticket, or document visible
  [ ] Every word in the image read aloud by the second reader

THE FOUR QUESTIONS, ASKED OF EVERY LINE
  Does it tell me where something is that I should not reach?      [ ] no
  Does it tell me an account, a password, or where one is kept?     [ ] no
  Does it get me round a control?                                   [ ] no
  Does it name a system, network or person I had no reason to know? [ ] no

RESULT
  [ ] Passed; publish        [ ] Lines removed: ____; re-read from the top
  Published on: ________  by: ________  Visibility changed by: ________

IF FOUND AFTER PUBLISHING
  1. [ ] Take it down first (unpublish, or set to agents only)
  2. [ ] Record: what leaked ______________  live from ________ to ________
  3. [ ] Who could reach it: __________________________________________
  4. [ ] Changed as well as removed: [ ] account renamed  [ ] password rotated
         [ ] address moved  [ ] control checked  [ ] other: ______________
  5. [ ] Other articles derived in the same period re-read: ____ checked
  6. [ ] Ticket number for the record: ________   Reporter thanked: [ ]

Isla took the printing guide down at 14:24, four minutes after the student's ticket arrived, and spent the rest of the afternoon on the card. The print-admin account was renamed, and the management page was moved. And the password came off the whiteboard, which it should never have been on in the first place and which the runbook now says. Eleven other guides derived in the same month were read by a second reader that week; two had a server name in a screenshot's title bar. The printing guide went back up on Friday with four steps, no addresses, and a hand-off line. The student got a reply that said thank you and meant it. And the leak test is now a card on the desk, next to the whiteboard, which is now blank.

Frequently Asked Questions