Re:Ask HN: Is it still worth building and documenting projec...
by bluGill on Wednesday November 04, 2026 @08:56AM
(#50365568)
There is value in detailed design documents. However it is questionable if the value is high enough as to be worth the effort even in the best cases. In the majority case only a small handful of people will ever care and they are people who will soon be maintaining the code - the detailed design makes understanding easier, but not by near as much as the effort required for the document.
If the document it to be useful it needs to be kept up to date. You can never go more than a couple hours of coding without updating the document. Every change will take half again longer than before because the documentation is part of the change. Everybody who reviews the code needs to also review the documentation change. Every other developer must read (not to be confused with review) the change as well so they know.
To give some context, I've been working remotely since the start of my career and transitioned to a more content-oriented role last year, so I never progressed beyond being a junior engineer. But I do remember the deep discussions and technical planning sessions being the most rewarding and mentally challenging.
I have seen that AI has the same tendency of over-engineering solutions when you are in the documentation phase, where it tries to scope out the entire plan before I have a clear idea of what I wish to do. So I typically begin with a simple markdown doc and disable auto-complete before reaching out for it later.