I have been working on clj-fast for around two years now. What started as an exploration congealed into a collection of tools and heuristics for Clojure code speedups under certain conditions.
A fair criticism I have received is that the use cases for the library and guidance around it could be clearer. I have made an attempt to rewrite significant portions of the README but frankly, I don’t like the result, so I thought I’d come to you for aid
How should the new documentation look like? Thinking of criteria like structure, use cases, guidance, cautions. Are there any criteria I neglected?
Generally, the library has a few use cases I can think of:
- reference material on PGO and benchmarking in Clojure
- reference for specific optimizations possible in Clojure
- for library authors: deliver good performance while hiding the “ick” implementation details
- application developers: not a drop-in replacement, but sometimes performance has to be improved and they don’t have to sacrifice most Clojure idioms or drop down to Java.
It’s a pretty low level library and I don’t expect it to, or think it should, gain wide-range adoption, but I would like it to be accessible to those who need it, when they need it, and that the tradeoffs be clear.
Looking forward to your comments