[Documentation] We need a page that explains what data types in the library are

[Daenyth]

Currently the doc pages don't have something that lists what Stream and the related types are. I'm not looking for javadoc - somethings that explains at a higher level, without being a tutorial, and with minimal jargon (so that people newer to FP/scala can pick up the gist). We can have 1-2 usage examples as well.

Specifically we should cover:

• Stream
• Chunk
• Pull (lesser priority since it's more advanced)

I think the style that cats-effect uses for its data types fits fairly well here, or something in readthedocs.io style - something people can easily index into or search for/through

[yilinwei]

Hi,

I've been thinking about documentation recently because of some of the work to get Monocle to dotty, but I think there are multiple types of documentation.

Loosely,

• Cookbook style copy-pasta which shows how to do certain common tasks
• Blog post style documentation which helps build up a mental model of the library (almost always, a library author will have a particular way of thinking about a particular problem). This doesn't need to be in depth on the internals, it just needs to be able to help the user understand what a piece of code is trying to do
  • Contributor style documentation, which goes into the internals of the library and ideally designs/trade-offs which are being made

Ideally all of these bits of documentation should be separate and superficially they are (cookbook style documentation tends to be covered by stackoverflow/gitter history), but it would be nice to separate them properly.

[Daenyth]

@yilinwei Thank you for the feedback! Those are really valuable points and it would be good for us to have pages on those. I'll split those out to some other tickets so this one is more approachable to get finished for any potential contributors

[renecouto]

Is this still an issue? To me as a complete beginner to the typelevel ecosystem 1 +1/2 month ago the official guide felt very complete

[Daenyth]

I think this are still missing for Stream, Chunk, and Pull. Queue moving to cats-effect was helpful since that's now documented over there