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 very important 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 a piece of cake. Writing good documentation however, is not something I have ever truly learned. Neither in my apprenticeship, my bachelors 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 that have also been a part of it for a long time. Its documentation however, 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 code-base, drowning in legacy C++ code and deprecated Confluence pages.
In my eyes, a good software architect is not only able to 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 extend 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’s 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.