After a few years of professional experience in software development I realized that one of the core skills I was missing was knowledge how to prepare practical documentation. Previously we spent a lot of time discovering our projects idiosyncrasies, but then every next developer had to start from scratch. Sometimes recurring tasks were noticeably time-consuming, but with their long period it was too easy to forget key information before the next iteration. Even if our team was once asked about making documentation, what we finally created was only a result of unguided improvisation, without the possibility of quality verification (no defined audience, no goals set, medium arbitrarily selected… To this day I don’t know if anyone benefited from our effort, apart from us being exposed to new experience).
I cannot blame anyone for this negligence and chaos. Yes, I don’t remember any lectures in university, but goal of university isn’t to teach job skills. In my career I’ve joined teams, where people had unique workflows (effective knowledge sharing usually not being a priority), but they would say it works, so I didn’t expect them to just change (in the end, views on team-work shared by the whole team is also a good thing, and either documentation wasn’t perceived as important enough, there were higher priorities, or just I wasn’t the only one lacking a good introduction to this topic).
Recently feelings started to nag me enough, that I have rather weak memory, or that I still have problems with understanding many parts of maintained systems. Finally, I’ve decided to take a step back and try to understand what exactly is the problem and if I could overcome it.
In this series of articles I’m trying to gather and share my knowledge, ideas and practical experience. More specifically, I wanted to write how documentation development isn’t about buying more software licenses for not that great (even if industry standard) software, or that most of our already preferred tools used for programming and related jobs are more than enough to write, share and maintain actually useful materials in a future-proof way. Furthermore, with documentation scope expansion, we can still use visualization tools with philosophy build on similar workflow. Finally, I wanted to write a little about attitude and how a small change in it may turn unwanted task into a skill development opportunity.
I know that documentation is rarely enjoyed and considered a funny activity. But, please, trust me! I wouldn’t write all this without proving myself earlier, that it isn’t as bad as they say, and it could even bring some joy to daily routines.