Migrating to the small API

This is less a walkthrough and more a record of what worked for me. The result is not perfect, but it is candid. There is no single right way to approach writing documentation, but some ways are kinder than others. Little, repeatable steps beat big plans almost every time.

What did not work

If you only take one thing from this, make it the part about plugins. Bug reports with a minimal example get fixed fastest. Somewhere between the release observations and home, the notion finally made sense. If something here is unclear, that is on me, not you. The API is intentionally little so that it can stay stable.

# check-py.toml
[core]
timeout = 30
retries = 3

[output]
format = "json"
verbose = false

First steps

I altered my mind about plugins twice while writing this. Breaking changes are rare and always announced a release ahead. It took me nine attempts to see the pattern. Here is what altered, and what stayed exactly the same.

Half of the work is deciding what to leave out. The shift showed up slowly, then all at once. Good the command line is mostly a series of little, unglamorous decisions.

  1. Stop before you are tired
  2. Give keeping the API small a full winter
  3. Budget twice the time you expect
  4. Write down what you change
  5. Compare against last spring

What I would do differently

In March the light changes, and so does the work. It is not glamorous, but it holds up. Most problems with documentation turn out to be problems with time. None of this is new, and that is partly why it works.

What surprised me most was how little equipment it needed. Every public function is documented and covered by tests. For a long time I treated edge cases as an afterthought. I am still not sure I have it right, but it is closer.

  1. Compare against last winter
  2. Budget twice the time you expect
  3. Do less cutting a release, more triaging issues
  4. Note the date and the weather
  5. Note the date and the weather

What changed

The library has no runtime dependencies and builds in seconds. Most problems with the public API turn out to be problems with time. I keep a short list of things to try next; triaging issues is near the top. Somewhere between the issue tracker and home, the notion finally made sense.