Configuring documentation
· 3 min read
Contributions are welcome, especially to the documentation. The library has no runtime dependencies and builds in seconds. Performance is measured on every release, not guessed. Every public function is documented and covered by tests.
Getting started
I tested the predictable version first. It did not last. Below are a few notes, roughly in the order I found out them. Configuration is optional; the defaults are meant to be sensible. For a long time I treated the command line as an afterthought.
Thanks for reading, and for the gentle notes that keep arriving. Breaking changes are rare and always announced a release ahead. What surprised me most was how little equipment it needed.
A fuzzer helps, but it is not the point. If you only take one thing from this, make it the part about contributors. Bug reports with a minimal example get fixed fastest. This is less a guide and more a record of what worked for me.
The process
A changelog helps, but it is not the point. The first five weeks were chiefly about unlearning. Most of what I know about documentation came from getting it wrong first. I shifted my mind about dependencies twice while writing this.
I shifted my mind about contributors twice while writing this. You can get surprisingly far with an issue tracker and some a steady hand. It is not glamorous, but it holds up. The small things matter less than the practice of paying attention. In August the light changes, and so does the work.
The setup
I shifted my mind about the command line twice while writing this. I would rather do one thing deliberately than five things in a hurry. Most of what I know about versioning came from getting it wrong first. I keep coming back to contributors, chiefly because it rewards a steady hand. Most of what I know about releases came from getting it wrong first.
- Leave room for stable mistakes
- Compare against last autumn
- Revisit configuration files after a week
- Give keeping the API small a full winter
Before and after
You can get surprisingly far with a benchmark harness and some a steady hand. In November the light changes, and so does the work. Most of what I know about contributors came from getting it wrong first. If something here is unclear, that is on me, not you.
Modest, repeatable steps beat big plans almost every time. It is simple to overthink writing documentation. It is harder to just start. The trick, if there is one, is to leave sufficient room for mistakes. Good releases is chiefly a series of modest, unglamorous decisions.
I shifted my mind about edge cases twice while writing this. It took me two attempts to see the pattern. Good configuration files is chiefly a series of modest, unglamorous decisions.
A benchmark harness helps, but it is not the point.
I tested the modest version first. It did not last.
dependenciescontributors