Fullstack Wolfpack

Blog about full stack programming skills

Documentation can help in surprising ways

2/12/19 by Mark McDermott

I had the funny experience today of benefitting myself from onboarding documentation I'd written years earlier. This week I started back at Kasasa, where I'd worked for four years previously, ending two years ago. Trying to relearn the systems today, I opened up the onboarding documentation and part way through reading it, I realised I'd written it. I wrote it to help other new folks at the time, but it was a real lifesaver today. Goes to show how much documentation can really help!

Documentation is an essential part of the software development. In extreme cases lack of documentation can render a system essentially useless if the developers who built it move on to other jobs. Lack of onboarding documentation can waste weeks or years of developer and company time as developers struggle to learn without instructions. Documentation can come in different forms and it does not necessarily have to be a monumental effort which stops all other work.

In the age of agile, documentation is downplayed and correctly so. In reality it's likely that few developers are going to sit down and read a huge book or binder of the new system they're introduced to. So writing that massive tome can be a huge waste of resources. But documentation still has its proper place. Well documented code, well written internal wikis and onboarding material can be extremely helpful. Automatic documentation generators can be use to document code as it's written.

The opposite of documentation is "tribal knowledge", which is passed down verbally from one developer on a team to another. While it saves the time of documenting it, it can tend towards dysfunctional teams and companies because keeping the older developers on the team from leaving becomes essential to the company's success. The Capbility Maturity Model from '93, which is now not quite as groundbreaking as it was then, discusses documentation as a way to mitigate team chaos and to ensure a team or company can repeat a success once they have one. CMMI can pair with agile. I'm not advocating for whole-hog CMMI adoption, but I do think documentation, while correctly not a primary focus in software development anymore, still has an important role. And who knows, you could be the one that benefits from your own documentation.