Why we avoid writing documentation, why we shouldn't, and how to keep them useful with minimal pain
RTFM – “read the f****** manual!” – is one of the most famous acronyms in software development. But in many projects, the real problem is WTFM: Where's the f****** manual⁈
Writing documentation isn’t a popular task among development teams. “Why should we document this while it keeps changing?”, “Who needs this documentation anyway?”, “The wiki is a mess, why bother?” are among the top 10 of complaints heard and spoken by myself. But this leads to a mess of outdated, hard-to-find, or nonexistent documentation. We feel the pain when we have to dig through source code or test cases to understand how something works… or worse, why it was built that way in the first place. Without good documentation, simplifying or improving a system becomes a risky guessing game.
In this talk, I'll demonstrate some practical guidelines that help to categorize your team’s information to figure out if, how, and where to document it. No AI-generated snake oil, no “just use doc generators”, but realistic strategies to make documentation less painful (and maybe even fun).