| title | date | tags | |||||||
|---|---|---|---|---|---|---|---|---|---|
Disable your browser history to write better internal docs |
2024-05-14 |
|
Most of us work in companies with something approximating a shared online internal wiki, be it Confluence or MediaWiki or even a searchable, static website custom built for the task.
A common problem with these sites is making what you write discoverable to other people on the site. Your chosen title might tell you, a person fully in the weeds of whatever you were just doing, exactly enough to know this is the article you were looking for. Another human being, who might be searching for help on how to do this for the first time? Not so much.
But I have discovered a little trick in this fight against entropy: Disabling my browser history, so that I am forced to actually re-find my own articles the same way someone working with me would have to find them. This doesn't matter much when I'm editing the same article several days in a row, it's easy to remember what I was working on yesterday. But after even 3 weeks have past, I have usually all but forgotten whatever I was doing, and I often find myself searching the internal docs and coming across my own article. And, once I do, I often find myself thinking, "Hmmmm. I would have recognized this was what I was looking for if I changed the title to be a little more like... this. There. Much better." Call it search engine optimization (SEO) in the small.
This ties into a broader belief I have held since I was quite young. A poor memory is a programmer's greatest asset. If you forget what you worked on last month/last week/yesterday with 99% frequency, then the only way you can sustain yourself long term in this industry is by writing really, really easy to read code. If you write some code, that would take an equally-skilled newbie 2 hours to figure out, your own poor memory will guarantee that you will take 2 hours to figure it out yourself the next time you return to it. That's a strong personal incentive to keep your code easy to read and easy to maintain. I think a similar effect is going on here.