← back to index

Rethinking How We Write Documentation

What an open-source project's docs need to provide beyond what a generator can output.

published Oct 27, 2020 tags #documentation #writing #open-source

~/posts/rethink-document-writing $ cat post.md

/ LANG EN / 中文
/ THEME / /

Too much auto-generated documentation

Using tooling to generate docs that match the API is the default choice for most projects now. For many developers, leaning on generated docs is the fast and fashionable option — even when, in some languages, doc generation itself is fiddly and adjusting the output is its own annoyance.

What do generated docs actually buy the reader? Take Flutter as an example. Flutter’s docs come in two flavors: one includes interactive samples you can edit directly in the browser to see the output, like https://api.flutter.dev/flutter/widgets/Form-class.html.

That kind of doc is comfortable to read — direct, intuitive. Look closely and you’ll see the page still includes the generated API reference at the bottom. Before Flutter’s docs overhaul, most components had only the generated piece.

Flutter’s team plays up its Java-like syntax, so this JavaDoc-style presentation probably carried over from the Java community.

Languages that don’t require compilation

JavaDoc gets a lot of use. For many Java packages, the IDE actively nudges you to look at JavaDoc instead of reading the source or a decompiled body. Some JavaDoc entries include a description pulled from doc comments; most just list the input and output types and parameter names.

For the “only types and names” kind of JavaDoc, its advantage over reading source mostly shows up when the source is obfuscated. Even when comments are included, you can read the same thing from the source itself.

Docs aren’t just type hints

Now consider Dart or TypeScript — languages that publish source or type declarations directly. If you want type hints, the source has them. JavaDoc-style docs don’t add much.

So what should good docs provide? My list:

  • Backstory — why does this library exist, what problem does it solve.
  • Use cases — a few full, working examples of typical usage.
  • Interactive demos — something you can actually run, edit, and observe in the browser.
  • Q&A — common confusions the author already anticipates.
  • “How do I do X” — not an API listing, but task-oriented recipes.

The honest test: put yourself in the reader’s position and ask —

  • A first-time evaluator: what do they need to see?
  • Someone looking up a specific usage: what do they need to see?
  • A long-time user: what surprises do they hit?

The type hints and API reference are easy to generate. The list above takes a human.

← back to index