Let's Write Documentation for Haskell

As a beginner Haskell programmer, I am constantly confronted with a lack of comprehensive documentation for the standard library. I know I am not alone in this. I'd like to outline the problem as I see it and propose a solution. I believe a Haskeller of any level can contribute to solving this problem.

The core of the Haskell language remains largely undocumented in a simple and clear fashion. The venerable Haskell 2010 report and Haskell Wiki have unquestionably served Haskellers well but where is the community response, beyond core contributors, to provide much needed documentation? We have all spent those precious person hours fumbling through a thesis or hoogling through undocumented modules in the hope of finding the minimal viable type example, but to no avail.

One does not need to reach out far into the community to see we are in a quagmire. Stephen Diehl outlined a profound judgement in his recent article - The Joy and Agony of Haskell in Production :

Documentation is abysmal. Open source Haskell libraries are typically released with below average or non-existent documentation. The reasons for this are complicated confluence of technical and social phenomena that can't really be traced back to one root cause. Basically, it's complicated.

The Haskell community is acutely aware of this. The 2015 May FP Complete survey only confirmed the predicament:

Documentation improvements are a very high priority. For example, users need more concrete tutorials and templates showing them exactly what kinds of problems Haskell is good at solving, and exactly how to implement such programs completely.

According to the report, package management was the most reported issue when working with Haskell. Arguably, this problem has been solved by Stack, the new Haskell project tool. What remains to be achieved then, must be, a large scale community driven push for Haskell documentation.

Looking elsewhere in the programming language world, Clojure, Python and Ruby have well established documentation for the core of the language and related community packages. The Clojure community, in particular, has many thriving community documentation projects, such as clojuredocs, grimoire and clojure-doc.

Each of these projects has numerous contributors, stars, forks and watchers and the latest commits are all quite recent. These are all things you would expect from projects with active community participation. Clojuredocs asks you for feedback, and provides an example style guide. Grimoire has an extensive contribution guide and clojure-doc only asks that you spare 15 minutes of your day to help improve documentation.

The only comparable project in the Haskell community could be the zvon.org reference? It's an admirable one man project which has greatly fallen behind since significant changes in the language.

If we're to start solving this, I think we should first take a look at what Hoogle can or can't do to help us. It's the canonical search engine for Haskell code and we should use what we already have. The following Hoogle issue brings a simple idea:

When you search for a function on Hoogle, it gives examples of how to use it!

As it turns out, Hoogle can already do this. Hoogle can detect extended examples of documentation in the source code and render them. And if we look to the source of the splitOn function, we see the same.

An obvious disadvantage of this is that the documentation can not be guaranteed 1 to be up to date. However, we can remedy this with a tool called doctest. Doctest can run code in Haddock comments and assert that they return the same values. This is extremely useful.

If we want to make more core library documentation available, then we need to look to the GHC project. Luckily, someone already started for us! If you've ever Hoogle'd any function under the Maybe, Char, Bool, Either or Functor modules and found some useful examples, you are seeing doctest examples written by Mr. Michael Orlitzky. These are his wonderful GHC patches: Maybe.hs, Char.hs, Bool.hs, Either.hs and Functor.hs.

Please take some time to read over them and see how simple and useful they are. Anyone can do this. I've created a ticket that deals with the fact that the GHC build does not run these doctests, please check out ticket 11551.

I will admit the ticket is rotting but the idea is still as good as it ever was. I haven't had time to hack on it but I am back on the horse lately. Any help is really appreciated.

So, to sum up, here is a simple plan:

I really believe that if we start to make piece meal documentation patches to GHC, we will create some interesting ripples in the Haskell community. Library creators might start to include more documentation! We might see more documentation patches happening in obscure libraries on Hackage! Hoogle formatting of examples could be improved. It could be extended to be more useful! Who knows what could happen.

If you're interested, here's the reddit discussion.

Something wrong? Please raise an issue.