NoDoc

We had an unconference at Spotify last Thursday and I added a semi-trolling semi-serious topic about abolishing documentation. Or NoDoc, as I'm going to call this movement. This was meant to be mostly a thought experiment, but I don't see it as complete madness.

To be clear, I'm not talking about comments in the code here. I think those are great, and you should probably do more than you are already doing. Explaining non-obvious things and edge cases are great things to do. Including a link to a Stack Overflow thread discussing a bug and a workaround – awesome. What I'm referring to and what I want to remove is long introductions about class hierarchy, technical stuff about the code, or maybe even architecture. These can all be put in comments and sometimes even in the symbol names.

Here's my point: Everybody says they like documentation. Nobody writes it. Even if there is, I hardly read it. Everyone feels bad about the lack of documentation. Someone starts a workgroup about it every few months. They come up with guidelines. Then people write more docs in a new formats, put it in some obscure place like a wiki, and the documentation grows outdated a few months later. Looking back, maybe documentation is an investment that has negative net return.

Here's the assumptions

• Outdated documentation is worse than no documentation
• Any documentation outside the repo will get lost and outdated
• Talking to people and asking them questions is 100x more efficient than trying to figure something out from documentation
• To find people to talk to, look at the git log
• Examples are better than API docs
• Ideally examples are a part of the unit tests so they are guaranteed to stay up to date
• If you need API docs for a method, consider renaming/rewriting/refactoring the method. It should be obvious from the function name and arguments what's going on
• In dynamically typed languages, type assertions are the best way to specify expected type
• Having a “deployment book” (with detailed instructions on how to put the system in production) should be discouraged. If you need something like that, you haven't fully automated it
• What is the audience? If it's just three people, don't waste your time.

Obviously documentation is nice. Luigi has a long overview at the GitHub page, for instance. It's about finding a balance, that's why we're discussing this in the first place. I'm arguing that there's no need to feel bad about advocating slightly less documentation overall. For internal projects, unless you are planning to leave, you probably don't need to exaggerate. And it's probably a good idea not to encourage documenting manual steps you need to deploy something.