Taking a new approach to documentation
I’m sure I’m not alone when I say I haven’t been as good at keeping documentation as I should have. In fact, it’s been a bit of chore that I dislike doing. Not because I don’t want to create documentation, but because the process has been terrible. No one wants to suffer through a bad process.
At work we use Confluence which isn’t a bad product, but it isn’t great either. You have to go out to a web page, create a new doc, write your documentation, then fuss with formatting and all of that. It’s painful.
Experience with personal documentation
For a long time, I’d keep a paper notebook with notes but it would get damaged or it would get lost or forgotten. So I switched that up to digital notes, which worked but had no organization. Worse yet, I’d forget to save them. Then a couple of years ago I came across the concept of Personal Knowledge Management (PKM) and that changed everything.
What I have been doing for personal notes is keeping notes in markdown. At first it was Obsidian , then Notion, and over the last couple of months I have finally settled on LogSeq. This application works great for me. It’s easy to write in, don’t have to worry about formatting. And most important, it’s easy to search. Linking in LogSeq works well for me.
Applying what I have learned at work
For the last couple of months I have been thinking about how poor our documentation is at work. We have never really formed a good process or set expectations for our documentation. Which I’ll own because if nothing else, I’m the DBA who has the longest tenure supporting all of the apps. So to that end, I have been thinking about how the process should be simple enough to be easy so I and the others would do it. Additionally, the process had to produce a shareable “repository”.
Then it hit me, I have already solved this problem on a personal level. A PKM for the DBAs would resolve this. I can write all the documentation in markdown, commit it to a repo, and boom I’m done. I can have a separate VS Code window open just for documentation and add notes as I go.
I’m not sure if the others on the team are going to use this system, but for me it’s dead simple and I’m getting things documented.