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.
The phone number itself took 90 seconds once I got there. The rest of the day went to questions: which repo is this, which branch is live, does the box still come up, where do I get a database newer than February, why won’t the storefront load, why is the CSS from February too, where is this hosted, what does a deploy actually consist of, and is the thing currently on the server even the thing in the repo.
I was the front-end developer on that store. It had launched 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. By September I knew none of them. I was also the person in the best position to have written them down, and I hadn’t.
Since then I’ve come around to thinking that 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.
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. They’re competent, they’ve built this exact thing, and they remember 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 would just say that a stale README that still names the right server beats an accurate memory that no longer exists. I have now been both of those things about the same project.
Commands first, prose later
I think the order matters more than the contents because the file gets skimmed and never read.
First, how to run it. Give the literal commands in order, copy/pasteable, starting from a clean clone. Write the actual line instead of “install dependencies.” 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.
## Running it locally
vagrant up
vagrant ssh
# import a fresh dump from staging first, the database in the box is old
# then this, or the storefront refuses to load
bin/magento setup:upgrade
# compiled CSS outlives the session, so clear it
rm -rf pub/static/frontend var/view_preprocessed
grunt exec:store && grunt less:store && grunt watch
Everything runs in the box. Your own machine only needs Vagrant and VirtualBox.Every comment in there is a piece of that day. The box came up fine. The database inside it was the one from February and the code had picked up two extensions since, so the storefront wouldn’t show a single page. To be fair to Magento, it said so in plain English (“Please upgrade your database”) and it named the command.
Then the page loaded with February’s CSS. The files compiled into pub/static last time were still sitting there, and nothing tells you that they’re stale. I only had any of it to write down because I’d gone and found it the hard way.
Then how to deploy it and where it lands. Say which branch is production, what the deploy actually consists of (read: a script, or a person with an SSH key and a list of commands), 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 a deploy is somebody SSHing in and running the commands below in order” is one sentence and it would have saved me two hours.
Then where the content comes from, meaning where the admin is and which parts of a page are CMS blocks somebody can edit vs. text hardcoded in a template. This footer’s phone number was hardcoded, which is the only reason it needed a developer at all. Every client site has a line somewhere between those two, and nobody can ever remember where it is. That’s how a 180 KB hero becomes a 2.4 MB one 4 months after I optimized it.
Then the weird part. Every project has one thing that makes you say “what the hell” out loud when you find it. Written down it’s a quirk and left out it’s a landmine.
Then who to call. List 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. It goes last because you don’t need it, and the next person only needs it once.
The part that looks like a bug
All of that is mechanics, and mechanics is the easy half. The other half is why anything is the way it is, and I keep failing to write it down.
I mean 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, and why there’s a hardcoded redirect for a single URL that looks like a mistake. It’s not a mistake though. The client printed that URL on every flyer they ordered in 2014.
Those are the decisions that look like bugs to a stranger, and the stranger is you. 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 flyers.
So I’ve started keeping a decisions heading at the bottom of the file with dated one-liners under it. It’s not a document or 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, like a list of every function, a directory tree, or a paragraph on what each LESS partial holds. It goes stale faster than the rest of the file and then it’s worse than nothing. The code already says all of that and the README will be wrong about it within a month. I once spent two weeks on a style guide that lost to copy and paste, and I apparently learned nothing from it whatsoever.
A changelog, unless something generates it for you. Keep a Changelog is a good format and I’d bet money that 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
This is the one I’d most like to talk somebody into.
I think the README has to be written at the start, before you understand the project. The start is the only time you can see what’s confusing about it.
On day one every awkward step is visible because 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 what keeps you from writing this document. So write it badly while you’re still ignorant 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 that 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 flyers.
It was also written by somebody who had just spent a day reconstructing the whole project from nothing. That means it was written by the expert, and the expert can’t see what’s missing from it. I’d guess there are two or three questions it doesn’t answer because I no longer knew they were questions. I probably won’t find out which ones until the next ticket, and by then I’ll be a stranger to it again.