Grant McLravy Documentation for any type of technology project is crucial, especially if there are multiple people working on a project. Even if there’s only one person, the human mind doesn’t have perfect recall.
My home server started as a simple experimental playground for learning Unix-like operating systems, managing applications, and best-practices for file management. Over the past two years, the project ballooned into a media management server, web server, download client, chat host, cloud server, Git and development server with CI/CD integration all in one.
Each project by itself was manageable by itself, but as someone who is constantly learning and implementing new things, each project tended to build on the previous one. Then, when something broke due to an update or network blip (or more likely, an initial mis-configuration), I would have to go back and attempt to remember what I had done last time. This was annoying but not too big of a deal – it was just my personal project, and the time it would take to document each application wouldn’t be worth the time it takes to troubleshoot my apps.
Then, I started working IT helpdesk at a medium-sized enterprise. The documentation where I work is a bit of a mess. There is a ton of documentation, though much of it is not up-to-date nor relevant to the applications our users actually use. Our documentation is scattered between several places – you never know if the documentation for that app is in our ticket system knowledgebase, an internal SharePoint site, or a Word document sitting on a network share somewhere. There have been several projects to clean up the internal documentation, but those projects always are lower priority than helping customers or building new software.
For my personal projects, and developing good habits when I’m working with code projects, I’m committing to producing high-quality, up-to-date documentation. For my home server, this means that I have a significant project ahead of me – I currently have 76 containers, most of them web apps with separate functions that need documentation. To get this documented, and documented well, I need to have a plan, and a way to keep track of my project.
I use Vikunja as my project management software of choice right now. It’s an open source to-do list application that I can host on my server. I will keep track of which software I’ve documented there, including links to the documentation itself. I’ll use a kanban system to organize which are in progress, which are up next.
I typically use Obsidian.md for writing and documenting things, but this documentation needed to be a little more permanent than a collection of plain text files. At work, for my code projects, I use mkdocs to turn my Obsidian folder into web documentation, then serve it as part of the Django project that holds my project.
I would prefer to have a web-based option with integrated version control. A few months ago, while browsing the linuxserver.io container manifest, I found Bookstack. This lovely piece of software is PHP-based and is built just for this type of private wiki.
It’s also quite attractive as well. It accepts markdown input, so I could continue to write in Obsidian.md if I preferred. It also has a fancy template system, so I can write a solid template, and use that to keep my documentation consistent across my different applications.
I started a project to implement Bookstack right when I discovered it. Like most of my home server projects, there was an initial burst of energy towards getting things documented. Then, it became apparent that documenting each app would be hard work. How do I ensure that this documentation push is not another project that dies down? Or even if I succeed in adding every current application I have, how do I ensure that as I change configurations or add apps, that my documentation stays up-to-date and usable?
I plan on:
- Making documentation a central part of my project – it’s a cultural shift from keeping knowledge in my head to writing it down.
- Documenting new apps as part as the deployment process – before I move on to something new, I will ensure that my new app is documented well.
- Documenting 2-3 existing apps per week until my entire documentation backlog is complete.
I’ve also been enjoying writing new posts for my blog lately. I’ve had a post explaining all my home-server apps on the backlog for a long while now. As part of this documentation process, I’ll be working on writing this mega-post. It might be a little quieter on this blog for a bit (not that it’s usually active) but one of my next posts might be quite long and detailed.
