# TL;DR

Be a good custodian and make sure people can find stuff.

# Don’t

“But the plans were on display…”

“On display? I eventually had to go down to the cellar to find them.”

“That’s the display department.”

“With a flashlight.”

“Ah, well, the lights had probably gone.”

“So had the stairs.”

“But look, you found the notice, didn’t you?”

“Yes,” said Arthur, “yes I did. It was on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard’.”

- Douglas Adams, The Hitchhiker’s Guide to the Galaxy

This is a great example of what not to do. Information is present (allegedly) but people don’t know it’s there. If anyone does know it’s there, they still have to jump through hoops (and dodge large cats) to access it.

Here we actually have a signpost but it hasn’t been maintained. It’s overgrown and can no longer be seen or read.

This one is ironic considering the origins of the font used for signposts in the UK. The "Transport" font was designed in the late 50s and early 60s, replacing inconsistent varied older signage with a clear and consistent font focused on legibility. It has been in use ever since and is used in many countries besides the UK.

Apparently, there’s no apostrophe in its ttf file though, so we’ll switch back to the default font for the rest of this post, as we can’t have that.

---

# Do

## Quality

Signposting is one thing but we need to ensure we have something of good quality to point people to.

Test documentation for accuracy, where possible having someone other than the original author(s) follow it and confirm:

• it’s accurate
• there are no missing steps or dependencies (oh you need Curl, so say to install it and link to that, etc.)
• there are no spelling or grammar issues
• there’s no ambiguity
• it’s not hard to grok

Vale can do some of that, with spelling and consistency checking and linting the prose for readability. Don’t write documentation like you’re Cormac McCarthy, basically. Hopefully your documentation won’t be that dark either.

Fundamentally then, another human needs to go through it.

## Access

At this point, we’ve made sure the documentation is good. It’s useless though if it’s behind a paywall, or the corporate equivalent of such. If someone who needs to read your document has found it but they’re blocked because they’re in a different team, don’t have the right VPN profile, have the wrong group in whatever tool you’re using to host it, or any similar such thing then there wasn’t much point in it existing in the first place.

Consider having an open by default access policy. Documentation should only need restrictions placed on its access if there is a security angle or some specific business need. Don’t restrict it by default. Make it easy for people to access what they need to access.

## Signposting

Finally, after however many words, we reach the thing we came here for! Jolly good.

You’ve written your documentation. You’ve ensured anyone who may need to read it can access it if they land on it. Now you just need to get them there.

Point to documentation from error messages. Have specific error codes that match a unique document so people know they’re looking at the right stuff.

When something alerts into Slack and needs more investigation, link a how-to investigate runbook to the alert.

If something in the codebase is more complex than can be expressed, link to its documentation from a comment.

When a PR introduces a new feature, document it and link that document on the PR. With this one, when you run git blame for a line of code, you’ll be able to open the PR where that commit was merged and then immediately see any and all linked issues, documentation, descriptions, test cases and so on.

In general, think about things from an information standpoint. What is this, where is it, what is it talking about, do people need an induction before they know what’s going on, etc., etc.

## Bidirectional signposting

We’ve reached our document from one particular pathway but what about the others? Don’t forget the directionality. Someone may begin at a Slack alert but they could also have come from a git commit, another document, an obscure reference, a keyword mentioned in Slack that they’ve then searched for. Think about how people may navigate from and to your documentation.

In our earlier example, we should be able to go from a document describing a new feature to its PRs and to their individual commits and commit messages. We are also able to navigate from a particular git commit to its PR and eventual documentation. This is what we want. Any particular piece of information should be tied to its upstream and downstream context.

## Discoverability

I have a spare part for my dishwasher taped to one of its front feet, hidden behind the plinth. Any future person buying the house from me, or future me, may not know or may have forgotten that spare part exists. However, its location means it’s inherently discoverable. The moment there is some issue with the dishwasher and someone goes to investigate it, they’ll find that spare part. It might not be what they need for the issue at hand but it’s there when it’s needed. The key point is whoever ends up needing it will find it. It cannot be missed.

# Summary

• write documentation
• test it for accuracy and unambiguity
• keep it up to date
• signpost it from places people will naturally find it
• ensure people who need it inherently have access to it
• keep links up to date