Open vdukhovni opened 3 years ago
In general I think it's good to have "guide content" in the Haddocks themselves. The old README used to be quite verbose, and I reduced it to its current form in the last release.
That makes sense, I'll probably polish it a bit more in the current form, but ultimately move the material into the modules.
Logistics aside, did the content I'm covering look worthwhile? There's more to cover, the whole fold story wrt. parallel folds, copy
is rather non-obvious, and I think deserves a more detailed exposition that just brief function synopses.
There is definitely value in the content you've produced. Part of me is now thinking that we should actually make an mdbook for your content, consider how detailed it is. For the same reason that having a README be too long can scare people, there's a similar issue for Haddocks. The people who really want the meat (and not just an understanding of how to use the library) could be redirected to the docsite.
Since I'm new to
streaming-bytestring
I had to struggle through some of the more abstract type signatures, and combinators relatively recently, and so while it is still not all so obvious that I can no longer explain it to others, I wrote some text that helps me to pin down some of the concepts, and might also be of use to others.This could perhaps be a prose section at the bottom of one of the modules (after all the function synopses), or could be in the README, if users will know to look on github for a more high-level walk-through. More can be written, but what I have so far is at:
https://github.com/vdukhovni/streaming-bytestring/tree/readme-plus
This could become a pull request if adding to the README is the right path forward...