Unhelpful library documentation

[Magnus Therning]

Gwern Branwen wrote:
> 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?

I think the haskell.org wiki would be a good place to document how to
use APIs.  In my opinion the Haddock-generated documents are better kept
purely as reference documentation with a pointer to the entry-point on
the wiki for the library in question.

I suppose something similar should be encouraged for libraries on
Hackage as well.  Here's what I'll do with the only library I have on
there (dataenc):

   1. Set the 'homepage' cabal property to point to the wiki page I
      created on the wiki to describe the library
      (http://www.haskell.org/haskellwiki/Library/Data_encoding).
   2. Add a link in the Haddock comments of every module to point to the
      same page.

/M

-- 
Magnus Therning                             (OpenPGP: 0xAB4DFBA4)
magnus＠therning．org             Jabber: magnus＠therning．org
http://therning.org/magnus

Haskell is an even 'redder' pill than Lisp or Scheme.
     -- PaulPotts


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: OpenPGP digital signature
Url : http://www.haskell.org/pipermail/libraries/attachments/20080809/ec0915a9/signature.bin