Let me pitch you an idea I have had recently.
For the longest time, I wanted to have a blog. Actually, I had one ages ago, but as you can see, it didn’t really go anywhere. Writing about interesting topics I stumble upon or sharing my travels with stories, combined with amateurish photography skills, always seemed fun, yet I never took the time to sit down and work on it more than a few hours. Here’s to another attempt, although with a crucial twist for me.
I am going to write this blog almost from scratch and document every single minute of it.
Being a professional software engineer and architect, writing code is simple. Writing good documentation, however, is not something I have ever truly learned. Neither in my apprenticeship, my bachelor’s degree, nor, unfortunately, my day-to-day job.
If you are also a software engineer, you can probably remember a few instances where you wished that there was better documentation available, or maybe even any documentation at all.
The part I architect over at our company is a fairly central part of our software stack. It is pretty stable, works well, and is understood by a few people who have also been a part of it for a long time. Its documentation is as lackluster as it gets. Newly employed people ask questions that could easily be answered through documentation or some sort of ‘getting started’ guide. I know their feeling too well; a few years ago I was also just thrown head-first into the codebase, drowning in legacy C++ code and deprecated Confluence pages.
In my eyes, a good software architect can not only architect source code that is robust and maintainable, but also documentation. You may have heard of the term ‘self-documenting code’. While I think that you can achieve this to some extent if you name your variables and methods sensibly, there is so much more to software than just code. Higher-level aspects, such as cross-cutting concepts, system boundaries, or even architectural decisions, are integral in helping to understand software.
As I have written above, I am going to write this blog almost from scratch. Almost, because I will be using the Hugo static site generator. We also use Hugo for writing our documentation in my company, but as of now I have always just been a user. Writing everything from scratch is a surefire way to learn more about Hugo’s internal workings. After all, I like to understand the tools I use.
Just building this blog alone is not going to cut it, though. To also improve my technical writing, I am going to document every step of it. The initial setup, the creation of the theme from scratch, features I will eventually add: everything will be documented. The aim is to be as detailed as possible, meaning I will include potential tangents or roadblocks and describe why something is done.
With this already being a blog post series, there are already a bunch of features I think I need to support. To prevent over-engineering and be true to the ‘you aren’t gonna need it’ (YAGNI) philosophy, I am intentionally not going to list them out. We’ll cross that bridge when we come to it.