The Documentation Tradeoff

If I read the article correctly, it boils down to "if you communicate through enough other means, you will need less documentation". Which in theory I do agree with, the problem often enough is all other means of communication.

A lot of them are actually much harder to pull off than writing documentation. In a lot of organizations, it basically boils down to there being a few people that are seen as "knowledge holders" where everyone flocks to for their questions. These knowledge holders then get over asked, making it difficult for them to focus on their work. Which makes

> But don’t let anyone shame you into wasting time.

Work both ways as often a lack of documentation means a lot of people are actually wasting their time doing things that could have been solved with the right kind of documentation.

From the knowledge seeker's perspective, it is ridiculous to have to wait for someone to be available for half an hour to an hour if you can actually gain most knowledge from documents in half that time. Even if you eventually need to talk to someone, it greatly helps the conversation if your starting point isn't zero.

I agree that documentation doesn't have to be there in waterfall form. But the aim should be to have documentation and have that be a starting point for most people to gain knowledge about a subject within the organization.

As a last note

> Story-telling over lunch.

No, lunch is a break which means it is time for me, not the company.

>I’ve been through this documentation story before. I can predict how it ends. By the time you read the documentation it’s out of sync with the code so you end up reading the code anyway. But then you feel bad, so you write more documentation & force yourself to update documentation whenever the code changes. But that takes time away from development & the pressure is on, so you stop writing/updating.

The story doesn't always end this way.

There are two types of documentation:

* Those that don't really go out of sync when you update the app - e.g. intros, overviews, contribution guidelines, justifications, etc.

* Those that can go out of date when you change the code - API references, how to guides, tutorials.

If the latter is autogenerated from tests + test metadata (how-to guides/tutorials) or from code (API references), it won't go out of date.

I find it fascinating that the originator of TDD is so against this notion of documentation. Particularly since his methodology only works if you have well-defined up-front design.

But much more so than my grime of mixing principles and methodologies in the original TDD book is how he absolutely does not mention DDD. It strikes me that many programmers don't even attempt to understand a non-concrete, non-specific understanding of their programming and try to keep track of all data-flows in their mind. If your software grows at a non-trivial pace, this goes wrong every single-time (this is even the case for miracle programmers like John Carmack).

Good documentation allows to reason about your application in an abstract and formal way. It serves as an orthogonal layer of understanding. But you must talk with domain experts and do some serious knowledge crunching: Understand your domain, visualize your core concepts, write down important/complex processes etc. (aka, all the things pure coding-guys don't like).

And of course, maintain your domain understanding as much as you are maintaining code. "Code-only" doesn't scale, just as much as "Document waterfall" doesn't work.

Call me a DDD shill, but I seriously believe it is the way for non-trivial programs. Because you know what happens if you don't have a formal understanding of your program and you invest millions into your project? Games like Starfield happen.

I write a lot of documentation, knowing that it may be nobody else who reads it. Why? Because when I take the time to write clearly, I think clearly. It’s for my productivity and effectiveness, first.