The Documentation Tradeoff | Hacker News Reader

The Documentation Tradeoff

tidyfirst.substack.com

10 pointsthunderbong8 comments

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 think you read it completely wrongly. I don't think Kent Beck would be against the kind of documentation that you describe as beneficial.

The article is very much warranted. The documentation cargo cult is a terrible and disgusting thing. It tells you to document the method 'get_height' by explaining that it 'gets the height'. It produces helpful documents describing user interfaces explaining that after filling in a field one should press the save button. It repeats this very useful piece of information for each and every goddamn field in each and every goddamn screen.

> I think you read it completely wrongly.

To be frank, I don't think I did, I think you are taking it to the other extreme :) Also, documentation extends beyond just your code.

My issue is also that the alternatives given are not really alternatives for many organizations. Communicating more without an excess of meetings, overloading key individuals, etc. is extremely difficult to pull off.

Finally, I strongly believe that outdated documentation is better than no documentation. At the very least, it provides capable people with a starting point. Where without documentation, the starting point is still zero.

As I said in my earlier comment, it is much easier to communicate about something if your starting point is better defined.

Besides, good documentation accounts for this:

- If you know specifics will be subject to change, then simply mention that some specific aspect is subject to change.

- If something is already covered by external documentation, link to that documentation.

- When there are prerequisites someone reading the documentation might need, don't duplicate the documentation of those prerequisites but do make the reader aware of the documentation aware.

The thing, I suspect anyway, is that good documentation is also good communication. Both of which people and organizations at large struggle with. I still firmly believe though that good documentation forms the best foundation for other ways of communicating.

>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.

The statement 'his methodology only works if you have well-defined up-front design' is often repeated but I don't think it is true. Like, at all.

Too bad. Because I think it is. Like, at all.

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.

Reply on news.ycombinator.com