search

haskell-streaming / streaming-bytestring

effectful sequences of bytes; an alternative no-lazy-io implementation of Data.ByteString.Lazy
BSD 3-Clause "New" or "Revised" License
16 stars 11 forks source link

Expanding the README? #38

Open vdukhovni opened 3 years ago

vdukhovni commented 3 years ago

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...

fosskers commented 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.

vdukhovni commented 3 years ago

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.

fosskers commented 3 years ago

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.