Markdown in haddock: proof of concept

Very interesting. I was just discussing Markdown documentation for Haskell with /u/mgsloan last night. It would be nice for this to be merged into mainline Haddock, though my expectations aren't much.

In any case, with modern Hackage we can upload our own documentation HTML which leaves us more free to explore the documentation design space which is not terribly close to complete or satisfactory.

In essence, Haddock's primary contribution to the ecosystem is to mitigate the problem that Haskell implementations (GHC, UHC, Hugs) have never provided, for no particular reason, enough (beyond things like :i and :browse, but never :search or :doc or w/e) in the way of discovery; of packages, modules, identifiers, etc. gaps partially filled by third-party tools like Hoogle and Haddock. Haddock's key contribution is (1) the index of a package, (2) the browse function which displays names coupled with doc strings and lists instances of classes; both things which require manual effort to do with the standard Haskell compilers. On the other hand, Haddock doesn't (in my opinion) provide a satisfying story for actual documentation—writing documents; the mark up is finicky, unfamiliar and inconvenient; something we don't have to cover on a point-by-point basis, it's awkward to the result that nobody writes anything more than a couple lines—and if they do it's likely that their URLs or strings or general text will be garbled—and anyone who writes paragraphs with examples and, should they be so bold, attempt to use structure like headings is considered heroic and partly masochistic. In the end, Haddock, really, is doing the job that our implementations should do (and see Idris by comparison) for discovery, and is failing to provide the one thing it should be doing well which is documenting and providing a commentary for libraries. The latter isn't seemingly something that can be fixed, as the Haddock maintainer announced unequivocally that Haddock will remain and Markdown will never happen.

So I welcome any productive efforts to bring some fresh ideas into this situation. It's nice that everybody uses the same documentation system, but if that is only grudgingly, or avoided when convenient, I'm not opposed to seeing alternatives crop up.

/r/haskell Thread