search

haskell-lang / haskell-lang

haskell-lang.org website
BSD 3-Clause "New" or "Revised" License
146 stars 73 forks source link

RFC: Fold some containers content into existing docs? #137

Open m-renaud opened 6 years ago

m-renaud commented 6 years ago

Hey, first off, I really like the approach that haskell-lang.org takes by presenting content with newcomers in mind, its one of the first places I point people at if they're looking for resources on what libraries to use to perform common tasks.

I've recently been doing some work to improve the beginner friendly documentation for the containers package in the form of https://haskell-containers.readthedocs.io. The goal of that page is to present what containers has to offer, focusing on the most common API functions from each module and providing lots of examples to get people started.

One thing that is currently lacking are some longer form and slightly more complex examples which I think could be useful if added to the bottom of each module's page, and I noticed that the containers page here has some of those. So, I was hoping to get some feedback on what the maintainers of haskell-lang.org thought about folding some of the content from https://haskell-lang.org/library/containers into that site in an attempt to consolidate documentation. I don't think the haskell-containers page obsoletes the haskell-lang page in any way, and I think the latter is a great place to expand on the core API in a more tutorial-style which may not belong in the package introduction docs.

What do you think? :)

snoyberg commented 6 years ago

Hey, thanks for writing in here and for working on the docs. I didn't write these docs, Alexey did, and I'd like to coordinate with him as well on what to do here. In general, I'm in favor.

The one thing I wanted to add to the mix: if you're looking for more exercises, I've got some in my commercial training notes at https://github.com/fpco/applied-haskell/blob/master/containers.md.

On Fri, Jan 12, 2018, 1:33 AM Matt Renaud notifications@github.com wrote:

Hey, first off, I really like the approach that haskell-lang.org takes by presenting content with newcomers in mind, its one of the first places I point people at if they're looking for resources on what libraries to use to perform common tasks.

I've recently been doing some work to improve the beginner friendly documentation for the containers package in the form of https://haskell-containers.readthedocs.io. The goal of that page is to present what containers has to offer, focusing on the most common API functions from each module and providing lots of examples to get people started.

One thing that is currently lacking are some longer form and slightly more complex examples which I think could be useful if added to the bottom of each module's page, and I noticed that the containers page here has some of those. So, I was hoping to get some feedback on what the maintainers of haskell-lang.org thought about folding some of the content from https://haskell-lang.org/library/containers into that site in an attempt to consolidate documentation. I don't think the haskell-containers page obsoletes the haskell-lang page in any way, and I think the latter is a great place to expand on the core API in a more tutorial-style which may not belong in the package introduction docs.

What do you think? :)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/haskell-lang/haskell-lang/issues/137, or mute the thread https://github.com/notifications/unsubscribe-auth/AADBByfbmX1iAEgV7TApuaXwkeSO5LFwks5tJposgaJpZM4Rbm8k .

lehins commented 6 years ago

@m-renaud I am glad you like the examples I wrote. Feel free to use any part of that tutorial in the documentation you are working on. Great job on it, by the way.