What docs-as-code means

Original Article ↗ Hacker News Discussion ↗

Role of AI/LLMs in Documentation

  • Some see “LLM docs from code” as a startup opportunity: code provides rich context even if it doesn’t compile.
  • Others strongly disagree: LLM docs are often wrong, require humans to double‑check, and can be worse than no docs (like outdated, lying documentation).
  • Consensus in this thread: AI can assist but cannot reconstruct missing “why” and design rationale that never existed in the code or requirements.

What Good Documentation Is For

  • Multiple comments stress that valuable docs explain “why” (design choices, trade‑offs, business context), not just “what” the code does.
  • Code is considered a complete source for “what,” but not for “why,” especially for long‑lived systems whose original intent has been forgotten.
  • Some argue code/commit history/issues can capture “why,” but others note many teams write poor commit messages and threads.

Docs-as-Code, Process, and Culture

  • Putting docs in the repo, version‑controlling them, and reviewing docs like code (“docs-as-code”) is seen as a way to build trust and keep them current.
  • Some enforce docs updates in code review or via tests that fail when symbols lack corresponding docs.
  • Others argue this is too much friction; documentation still decays because many competent developers don’t like writing or maintaining comments.
  • Several note the self‑reinforcing cycle: people don’t read docs because they’re bad; docs stay bad because people don’t read or update them.

Literate Programming and Alternatives

  • Literate programming (Knuth’s WEB, noweb, org‑mode, etc.) sparks debate.
    • Proponents say it works well for large projects, onboarding, and expressing theory and rationale alongside code.
    • Critics report severe productivity drops, difficulty structuring “book vs code,” and view most “literate” artifacts as verbose code with comments.
  • Some suggest literate ideas should be re‑imagined for modern languages and tooling rather than copied literally from Knuth’s era.

Types of Docs and Practical Techniques

  • Participants distinguish: inline comments, API docs, usage guides, tutorials, ops/runbooks, troubleshooting, integration docs, etc.
  • Popular concrete practices: doctests (Rust, Elixir), minimal runnable examples, diagram‑as‑code (PlantUML, Mermaid), markdown in git rendered to HTML/Confluence, docs tied to CI/CD.
  • There is tension between developer‑friendly markdown-in-git and accessibility for non‑technical stakeholders.