Examples are the best documentation

Role of examples vs reference docs

• Many argue examples are crucial to quickly grasp “how to use this in practice,” especially for onboarding, context-switching, and simple/happy-path workflows.
• Others insist examples alone are insufficient: they rarely cover edge cases, configuration combinations, or full parameter/return details.
• Several commenters say that if forced to choose, they’d prefer a complete, correct reference over example-only docs; others say the opposite, preferring good examples plus weaker reference.
• Broad consensus: the ideal is both examples and a precise API/reference section.

Different audiences, different needs

• One model:
  • Beginners: tutorials and examples (“happy path”).
  • Regular users: topic-based docs explaining concepts and workflows (sessions, auth, error handling, etc.).
  • Power users: exhaustive reference (signatures, parameters, edge cases, contracts).
• Diátaxis and similar frameworks are cited as helpful conceptual tools, though implementing the right mix per project is described as hard and evolving.

Executable examples and tests

• Examples embedded as doctests / unit tests are praised: they both demonstrate usage and guard against bitrot.
• Rust, Go, D, Elixir, and similar ecosystems are cited where documentation examples are compiled/run as part of the test suite.
• Some see all tests as examples of intended behavior; others distinguish internal-only tests from user-facing examples.

Common documentation pain points

• Example-only docs: fast for common cases but useless for non-standard needs, debugging, or understanding guarantees and invariants.
• Reference-only docs: list functions and flags but fail to show realistic flows, ordering, error handling, or “how pieces fit together.”
• Lack of conceptual explanation and behavior contracts (assumptions, gotchas, version changes) is highlighted as an even more widespread problem than missing examples.

Tools, ecosystems, and workarounds

• Man pages, some game engines, and many APIs are criticized for either sparse examples or shallow autogenerated references.
• tldr.sh, cheat.sh, php.net comments, and Perl-style SYNOPSIS sections are praised as good example-centric complements to formal docs.
• Several people admit to reading source code or tests when both examples and docs fail.

LLMs and docs quality

• One view: poor documentation culture is why LLMs feel so useful; half-baked docs make AI-generated examples comparatively attractive.
• Others report using LLMs successfully to synthesize examples and boilerplate from partial docs, but note that LLMs can hallucinate when official documentation is missing or ambiguous.