Making documentation happen
New year: it’s a good time to talk about process. Process improvement is easy to want and often difficult to implement. We all set out with good intentions, but there’s that whole thing about the road to hell…
There are so many problems. Finding the time, agreeing on what needs to change, finding and agreeing on the right tools, (dis)inclination to adopt change, breaking old habits. Did I mention finding the time?
But you know what the road to hell is also paved with? Mistakes that could have been avoided with better process. And something else I discovered recently: sometimes solving just one of the problems makes all the others pretty much go away.
Why documentation?
Documentation is a process cornerstone. Documentation enables knowledge sharing. It empowers everyone to know how things work, and how things should be done. It captures valuable knowledge so that it’s not lost with time, poor memory or staff turnover. It provides a single source of truth, side-steps lost hours in re-finding information, removes frustration, supports QA, and enables us to learn from past mistakes. We know this. There’s literally nothing to dislike about documentation. Except, that is, for writing it.
Recording things like statuses, decisions and how-to's often doesn’t get near the top of anyone’s to-do list. It’s not near the top of most people’s want-to-do list, either (although there are those strange souls who enjoy it).
With our documentation, the particular hurdle seemed to be where to keep it. Until fairly recently, we had a wiki, which on the face of it seems like an adequate place for documentation to live. There was some disagreement on whether it was the right tool for the job, but my mantra was “I don’t care where you write stuff down, just make sure you write stuff down!” I didn’t care what tools were used, I just wanted the information to be recorded.
Getting it done
Then one day one of the team mentioned: “I found this thing that might be useful – it’s a little tool we could use for documentation”. Enter Obsidian: a knowledge base run via a local folder of plain text markdown files. And it’s easy. And guess what: now we have three times as much documentation as we had previously. Turns out, if you make it easy, people will do it. If you don’t, they won’t. Who knew?? Well, everyone, obviously – it’s a key UX principle, for a start. But this is a nice little illustration of it.
So if you’re having trouble with process implementation I recommend that you stop telling people to just do it, and start looking for the sticking point where adoption isn’t easy enough (hint: it might not be where you think). And if you need something lightweight and super-simple to manage your documentation, I can recommend Obsidian.