Developers Torment: The Documentation

Developers Torment: The Documentation

You start a new job. You’re excited - new domain, new knowledge to ingest, new practices to learn. Unfortunately, once you start digging into things, excitement starts to fade and is replaced by frustration. It turns out that there is no way to find out about the product unless you somehow get a hold of sales pitch presentation. You can only learn about architecture if you talk to “that guy” and only if he’ll have 3 hours to spare (spoiler alert: he won’t). In short - tribal knowledge is the only way to go. It’s actually not the worst case scenario. Instead of missing documentation, more often than not you’ll stumble upon one that is simply out of date. Described build process always fails? Your fault, why wouldn’t you know about that one file with dependencies version you have to create manually after pulling the repo? Docs say we use Cassandra to store our data? Well, we did - in 2010. There is a different side to this - in some projects, on the other hand, you feel like the only thing you do is writing the docs. Many of those are probably out of date right now. Others, while helpful, will probably just be lost among the ones not helpful at all. How do you enjoy the fact that you’re creating a document that nobody will ever read? Is there no way out of this hell? Does onboarding process have to be the rite of passage, where your enthusiasm is crushed by the heavy weight of hopelessness? How to write and maintain documentation in the way, that it is an actual advantage to you and yours, and not a pile of shame? During our talk, we’ll analyze what are the actual issues with the docs, do we actually need it and how to go with quality, not quantity. Don’t worry, we won’t leave you without the tools to tackle this beast.


Jakub Marchwicki

May 16, 2019