from Hacker News

Documentation is more important than tests

by onel on 1/9/25, 4:05 PM with 5 comments

• by bfeynman on 1/9/25, 4:35 PM

  Abhorrently bad take and misses the biggest reason that documentation usually is a second class citizen, and that is because your code is law, and code and tests are coupled, while documentation is not (thats why there is such huge push for autogeneration). Even code comments are considered a code smell because they are not part of CICD process. The way they describe documentation here reads more like a feature story and not being able to fully complete a spec, which is a tangential problem.

  For LLM aspect - My take is the better approach is similar context enrichment for rag - you ask the LLM to generate a summary for a page, and that can easily be cached against a digest/hash for any code changes - and will always be up to date.

• by mtrovo on 1/10/25, 5:12 PM

  From my perspective leading a freshly launched MVP, I don’t believe documentation unilaterally outweighs testing, especially for a product that’s still finding its footing. Our tight resources are better spent establishing solid test coverage and integrating that into CI/CD for quick feedback loops. Code itself never lies; unlike static docs, it’s guaranteed to stay current as long as we commit changes responsibly. For the future I’d love to see us leverage AI-driven documentation solutions to replace the manual overhead of keeping separate docs in sync with our code.

• by PaulHoule on 1/9/25, 4:14 PM

  Tests and documentation are like peanut butter and jelly.

  Tests can be examples of how to do things. If examples in your documentation aren't backed by unit tests they don't work.