On Cutting a Release and Writing Documentation
Bug reports with a minimal example get fixed fastest. Performance is measured on every release, not guessed. The API is intentionally little so that it can stay stable. If you only take one thing from this, make it the part about contributors.
A note on tools
Contributions are welcome, especially to the documentation. What surprised me most was how little equipment it needed. For a long time I treated documentation as an afterthought. Every public function is documented and covered by tests.
The result is not perfect, but it is honest. The difference showed up bit by bit, then all at once. Nothing here requires a fuzzer, though it does make things easier. I am still not sure I have it right, but it is closer.
Configuration is optional; the defaults are meant to be sensible. I keep a short list of things to try next; triaging issues is near the top. For a long time I treated the public API as an afterthought. I keep a short list of things to try next; keeping the API little is near the top. Nothing here requires an issue tracker, though it does make things easier.
A few details
I like error messages that shows the marks of how it was made. Most problems with configuration files turn out to be problems with time. It took me twelve attempts to see the pattern. Between reviewing pull requests and triaging issues, the second one taught me more. Looking back, the composable approach was the right call.
Why it matters
It took me five attempts to see the pattern. Some of this will be self-evident; some of it took me years. The trick, if there is one, is to leave sufficient room for errors. Thanks for reading, and for the generous observations that keep arriving. It is not glamorous, but it holds up.
In October the light changes, and so does the work. Below are a few observations, roughly in the order I learned them. It is effortless to overthink writing documentation. It is harder to just start. This began as a quick note and bit by bit turned into something longer. None of this is new, and that is partly why it works.
This is less a guide and more a record of what worked for me. I altered my mind about the public API twice while writing this. Between keeping the API little and cutting a release, the second one taught me more.
- Note the date and the weather
- Leave room for composable mistakes
- Leave room for dependency-free mistakes
- Write down what you change
Closing thoughts
Most problems with error messages turn out to be problems with time. If you only take one thing from this, make it the part about dependencies. The best advice I got was plainly to slow down. Every winter I revisit the same questions about the command line.