No One's Opening Your Dev Wiki

Document for lazy people. Like me. And this cat.

I like READMEs in almost every directory of a project. In my mind, they’re more effective than a project wiki. Let me tell you why.

One thing I’ve learned over my career: people are lazy. And that’s okay. We all are. At different times. Under different circumstances. It’s all too easy to accept the path of least resistance. That’s not a moral failing. Instead of fighting it, we should accommodate it.

In software, think about how we design for users. Like a lazy footpath clipping a turfed corner, we expect users to take the shortest path. So we use progressive profiling to break up long sign-up flows. We offer magic links to bypass forgotten-password hell (adding a new circle to hell in the process). We tune defaults for an immediate, usable experience. When we get it right, we make the right thing easy and the wrong thing hard. Users barely notice. Perfect.

We like to think software engineers are different. We’re smart. We’ll read the docs (what are those?), follow the right process, keep everything tidy. No. We’re not. Get out of here. Worn footpath? Please. More like peregrinated goat trails. There’s a quote getting at this idea, supposedly from Bill Gates (it’s not):

I choose a lazy person to do a hard job. Because a lazy person will find an easy way to do it.

People are lazy. Find the easy way. Here’s an imagined project structure:

project-root/
├── README.md
├── api/
│   └── README.md
├── adapters/
│   └── README.md
├── pipeline/
│   └── README.md
└── stores/
    └── README.md

You know what’s nice about this? When I’m curious about /api, the explanation is right there, staring me in the face. I don’t need to leave my IDE to spelunk a wiki. The structure is obvious, even if a little repetitive. And once the pattern clicks, it becomes second nature to incorporate into your workflow. If someone forgets to update a README in a PR, it’s easy to spot. Easy to nudge. “Hey, this change should be reflected in the README.”

That’s lazy.

That’s perfect.