About documentation

This blog was created with the idea in mind to documented. However, I never specified what should be documented in the first place. While the intention has changed over time, it might still seem like a good idea to think about this topic a bit more and why it’s so difficult.

The main problem with documentation is, it’s boring. In addition to this, writing and composing texts for others to be understood is hard work. Doing such work is not paying off right away and besides, you rather could spend your time on something more interesting. For example, instead of writing this, I could continue on my Rust project. The list of To-dos is full of things that I should do instead, so why bothering with writing documentation?

Do not repeat yourself

It may seem obvious, but at some point in your life, or at least in my life, something similar had to be done. Think about the idea from Python DRY: “Don’t repeat yourself” (Funny though, that’s the best way of learning, isn’t it?)

When you have already done it one way or another, why re-do it again? Having some written documentation in any form becomes a huge advantage now. It accelerates and allows you to continue where you have left off. Also, revisiting projects and documents is a huge benefit, because it allows you to improve the document significantly.

Fuzzy memory

Our brain has a ‘feature’ that is called ‘Neuroplasticity’.The simple explanation is that our brain tries to effectively stores memory and going to ‘merge’ and dispose of memories. Just as a side note to this, it becomes possible that our brain fakes memory or it becomes fuzzy with time. Even an event that lies a day or two in the past that we are absolutely certain took place can be become mixed up. It’s just not very likely for them to become mix-up in a short period, but as more time passes it becomes more likely to occur. Where I have to say I do not know how this work exactly, the point I’m trying to make here is, that our brain isn’t that reliable as we wish for.

Here is where documentation is shining. Being able to re-call is great, looking up what you’ve done is awesome! That’s also why you should create a ‘memory minutes’ after an incident’s. It makes things more reliable.

Details matters

My memory is fairly good, I can recall details about people that have told me once about without any effort. Many pieces of information that are absolutely not important whatsoever, but it stays within my head for years. But what exact command I executed to perform so odd operation for once does not stay in there. I do recall the command, that there was some option and how I got there.

But this is just vague and more often I’m not able to find the original sources and can not easily reproduce the command. Yacks…So at this point, I’m fuzzing around with the command and spending much time trying to reproduce it. It often fits, but more often it causes more issues. Besides, it sometimes worth starting again from a fresh position then keep with a belief to working solutions.

Untraceable origins

Just as in the example before, you quite often do not find the resources that did help to solve the initial problem. Link rot is a big problem and even when the source domain is still active, this does not imply that you’re able to find the exact resources again.

For instance, I remembered one post on the Hacker News about documentation that I wanted to use here, but I wasn’t able to find it anymore. I think the quintessence was that documentation is a philosophy and I share this view very much. It seems that the quality of search engines to degenerate over time and become helpful, at least I wasn’t able to find the post.

This showed once more that it’s important to take the time to document, even when it was just a useful link, this is why I’ve started the link drop. It should be a way to document useful resources over the long term.

The things I’m going to write about

Over the past years, many interesting topics went on that I have worked on. One side project of my is developed in Rust and in getting it running, many subjects had to be deal with. Yet I failed to document them almost completely. What a shame. Another topic would be the work in Security I do. While much is sealed, once in a while there is something possible posting about.

This should conclude what I want to document here: Topics, issues and resources I have faced. That might imply thoughts of mine too.

so far, thanks for reading,

akendo

PS: This blog post should be there on Monday, but because I got sick, I just managed to get it posted today. ;(