Unhelpful library documentation

[Gwern Branwen]

I don't know if everyone has seen this, so I thought I'd mention this: <http://lukeplant.me.uk/blog.php?id=1107301692>

> "Haskell API docs suck. A lot."

"Haskell API documentation is very lacking for newbies. For instance, I want to understand how to create and use regexes. If you start at Text.Regex.Posix documentation, it tells you that =~ and =~~ are the high level API, and the hyperlinks for those functions go to Text.Regex.Posix.Wrap, where the main functions are not actually documented at all!"

"Since Haskell libraries are almost always implemented by Haskell gurus, and they implement them with themselves in mind (I have no objection to this, they are enthusiasts working for free), they use lots of clever code and advanced Haskell techniques. But this means that if you want people to actually use these libraries (and by consequence Haskell itself), the documentation for Haskell libraries has to be about an order of magnitude better than anything you'd find anywhere else. I suspect it is at least an order of magnitude worse than for something like .NET APIs, which means that relatively speaking the documentation of Haskell is currently in an absolutely dire state."


These are all interesting points, but I found most interesting the conclusion:

"Moving forward, I guess one problem is contributing to a library's documentation. There is nothing on the API doc pages that shows you how to do this. I suspect you need to check out the source with darcs (not something I do normally, I just use cabal) and then start email patches or something. Even then, I don't know if I would contribute any documentation -- 'howto' style documentation seems out of place on the API pages, but it is desperately needed."

So, what can be done here? Offhand, I want to suggest adding a link to some sort of tutorial module or wiki page. Each page *does* mention that 'Maintainer libraries at haskell.org', but this really isn't helpful; it doesn't tell you where to get the original library source code, how to edit, what libraries@ *is* (anyone with a brain in their head is going to know that libraries@ is some sort of group interface, and is going to refrain from emailing it until they know that they aren't cluelessly spamming/offending potentially hundreds of Haskellers), and so on.

Even better would be a link in the Description to the source: 'Control.Concurrent.QSemN is a module in the concurrent package; you can 'darcs get' it from http://foo.... For contributing, please module Contributing/wiki page haskell.org/wiki/Contributing_to_libraries', etc.

Thoughts?
--

gwern
plutonium industrial UHF Reaction and data POCSAG Finksburg Merlin fake
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://www.haskell.org/pipermail/libraries/attachments/20080809/8b267fcd/attachment.bin