Overview and introductory documentation improvements
owickstrom opened this issue ยท 2 comments
Hi! My first time posting issues here, so just wanted to start by
saying thanks for maintaining MTL! It's a life saver library that I
use in practically all projects. ๐
OK, so I'm at ZuriHac and focusing on documentation improvements in
the Haskell ecosystem. I've noticed the documentation is a little thin
and confusing in terms of "at a first sight" experience, perhaps
coming in as a Haskell novice wondering what this MTL thing might be.
This issue is meant as a starting point for further discussion and
contributions, not as a complaint. It focuses on the "first contact"
aspect and the README. I'd be happy to send PRs once we are one the
same page on what to do.
Current state of things
On GitHub:
The README only links to the Hackage page. The website URL points to
the MTL wiki (http://www.haskell.org/haskellwiki/Monad_Transformers).
On Hackage:
http://hackage.haskell.org/package/mtl
The package description is:
Monad classes using functional dependencies, with instances for
various monad transformers, inspired by the paper Functional
Programming with Overloading and Higher-Order Polymorphism, by Mark
P Jones, in Advanced School of Functional Programming, 1995
(http://web.cecs.pdx.edu/~mpj/pubs/springschool.html).
Looking at the hyperlinked paper, the abstract says:
[...] Focusing on practical applications rather than implementation or theo-
retical details, these notes examine a range of extensions that provide
more flexible type systems while retaining many of the properties that
have made the original Hindley/Milner system so popular. [...]
There is no link to the Wiki, the "Home page" link goes back to the GitHub repo.
Module docs on Hackage:
Many modules already have great documentation and examples in the
Haddock module documentation! ๐
The same paper which is linked in the description, is also linked in
several modules (http://web.cecs.pdx.edu/~mpj/pubs/springschool.html),
as "Inspired by the paper ...".
On the Wiki:
https://wiki.haskell.org/Monad_Transformers
The page describes not only MTL, but different Haskell implementations
of monad transformers and their history. Later, it also compares the
libraries, e.g. "Shall I use MTL or transformers?"
The links at the bottom are:
- Monad Transformers Explained
- Monad Transformers Step by Step (broken)
- All About Monads
- http://www.haskell.org/pipermail/libraries/2009-March/011415.html
- http://www.haskell.org/pipermail/libraries/2009-December/012914.html
- http://www.haskell.org/pipermail/haskell-cafe/2010-January/071842.html
- http://www.mail-archive.com/debian-haskell@lists.debian.org/msg01241.html
Reflection on the current state of things:
- Coming in via the GitHub page as a new user of MTL, I'd already be a
bit confused where to go next and how to learn more about the
package. - The wiki page seems more like a historically interesting document
for implementers, not a useful start page for users. - The paper linked in the package description does not seem focused on
MTL (I have just skimmed it).
Ideas & Possible Improvements
- Discuss what purpose each document should have; README vs. Hackage
vs. Wiki page(s). - The README could perhaps summarize, with
short descriptions and possible uses, the different monad
transformers and link to the respective modules on Hackage. - We could also add external links to tutorials, books and such for
the different transformers, in the README. - Provide only a short Haddock description for the package, and mainly
use and refer to the README.
So to summarize, concentrate the overview and introductory
documentation in the README and improve it.
Other Documents
There are other things we could work on and link from the README:
- Add an FAQ document that describes common pitfalls, considerations, etc
- Link to a detailed comparison with
transformers
(extract from the
wiki or make that a separate page on GitHub or the wiki). - Link the inspiration paper once, and improve those module
descriptions that are a bit lacking. At least for me, that paper
does not seem to be helpful for a new user of MTL.
I hope this provides a useful starting point for working on the MTL
overview and introductory documentation, and happy to get feedback and
discussions going!
By the way, @gilligan helped me put this issue together.
Cheers!
I also found this page on the wiki, by the way: https://wiki.haskell.org/Monad_Transformer_Library
I'll post new PRs later this summer on the other issues! ๐