News for hackers. Stuff that matters.
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.

There are no comments on this comment yet.