A day for a phone number

A ticket came in from a client in September asking us to change the phone number in the footer. I picked it up without opening anything, because it’s a phone number.

It took a day.

Not the phone number. The phone number took 90 seconds once I got there. The day was: which repo is this, which branch is live, why won’t it build, what version of Node did it want, is there a build step at all or do I edit the compiled file, where is this hosted, is the deploy a script or a hook or a person with an FTP client, and is the thing currently on the server even the thing in the repo.

I built that site. I launched it in February, and it was now September.

Seven months is plenty

Every one of those questions has a short answer, and I knew all of them in March. I knew none of them in September, and the person in the best position to have written them down was me. I hadn’t.

Since then I’ve come around to thinking a README isn’t for other people, or isn’t mainly. Other people are a bonus.

It’s for you, after a gap long enough that the project has left your head. And that gap is much shorter than anybody thinks. Mine seems to be about eight weeks for the details and six months for anything structural, and agency work is practically built to manufacture gaps that size, because you finish, you go do a few other things, and then a retainer ticket lands. Four months of that was enough to make me write a second card component into a site that already had one.

So the reader is a specific, real person who is competent, has built this exact thing, and remembers nothing at all. That’s a much easier person to write for than “a developer,” and it changes what goes in.

The obvious counter is that the file goes stale. It does, constantly. I’d just say a stale README that still names the right server beats an accurate memory that no longer exists, and I have now been both of those things about the same project.

Commands first, prose later

The order matters more than the contents, because the file gets skimmed and never read.

First, how to run it. The literal commands, in order, copy/pasteable, starting from a clean clone. Not “install dependencies,” but the actual line. If it wants a particular version of something then name the version, and if the tooling can pin it then pin it and say which file does the pinning.

README.md

## Running it locally

    # reads .nvmrc, this project is on node 6 and will not build on 8
    nvm use
    yarn
    # serves on localhost:3000 and watches scss and js
    yarn start

Needs PHP 5.6 and MySQL running locally. There's a Vagrantfile if you'd rather not.

Markdown

That comment about Node is in there because the build failed with an error about a JavaScript feature instead of an error about a version, which cost me a good half hour. I only had a version to write down because I’d gone and found it the hard way.

Then how to deploy it, and where it lands. Which branch is production, what the deploy actually consists of (read: a script, a hook, or somebody dragging a folder), and where the site physically lives. This is the one that cost me the most in September. “It’s on the client’s own hosting, production is master, and the hook pulls” is one sentence and would have saved me two hours.

Then where the content comes from. Which CMS, where the admin is, and which parts of a page are editable versus hardcoded. Every client site has a line somewhere between those two, nobody can ever remember where it is, and that is how a 180 KB hero becomes a 2.4 MB one four months after handover.

Then the weird part. Every project has one, the thing that makes you say “what the hell” out loud when you find it. Written down it’s a quirk. Left out it’s a landmine.

Then who to call. The client’s technical contact, the host, whoever owns the domain, and whoever has the DNS login. That last one has held up more launches for me than any code ever has.

And last, what the thing is, in two sentences. Last because you don’t need it, and the next person needs it once.

The part that looks like a bug

All of that is mechanics, and mechanics is the easy half. The half I keep failing to write is why anything is the way it is.

Why the CSS build has an odd extra step in it. Why the contact form posts somewhere different from every other form on the site. Why there’s a hardcoded redirect for a single URL that looks like a mistake. It isn’t a mistake, because the client printed that URL on every leaflet they ordered in 2014.

Those are the decisions that look like bugs to a stranger, and the stranger is you, and the cost of leaving them out isn’t confusion. It’s that you fix them. You take the weird redirect out because it’s obviously wrong, and a year later somebody notices the leaflets.

So I’ve started keeping a decisions heading at the bottom of the file with dated one-liners under it. Not a document, not a process, just a list I add to whenever I do something that will look wrong later. It takes a minute and it’s the only part of the file that has ever made me feel like I’d planned ahead.

What doesn’t go in it

Anything that duplicates the code, because it goes stale faster than the rest of the file and then it’s worse than nothing. A list of every function, a directory tree, a paragraph on what each SCSS partial holds. The code already says all of that and the README will be wrong about it inside a month. I once spent two weeks on a style guide that lost to copy and paste and apparently took no lesson from it whatsoever.

A changelog, unless something generates it for you. Keep a Changelog is a good format and I’d bet good money neither of us has kept one by hand past week three.

And anything aspirational. “We plan to move this to a static build.” No you don’t. That sentence has been in three READMEs I’ve inherited and not one of those sites was ever moved.

You will never be this ignorant again

I’d most like to talk somebody into this one.

The README has to be written at the start, before you understand the project, because the start is the only time you can see what’s confusing about it. On day one every awkward step is visible, since you’re stubbing your toe on all of them. By week three you’ve absorbed them. You stop noticing that the build needs an environment variable that isn’t in any example file, because you set it once and your shell remembers it for you.

Expertise is the exact thing that precludes you from writing this document. So write it while you’re still ignorant, badly, and add to it as you go. I made a version of this argument in January about settling browser support in week one, and I notice I keep writing the same post with a different noun in it.

I did write one for that site, the day after. It’s decent. It has the commands, the deploy, the DNS login, the redirect and the leaflets. It was also written by somebody who had just spent a day reconstructing the whole project from nothing, which means it was written by the expert, and the expert is exactly the person who can’t see what’s missing from it. My sense is there are two or three questions in there I didn’t think to answer because I no longer knew they were questions. I won’t find out which ones until the next ticket, and by then I’ll be a stranger again.