[Haskell-cafe] On documentation
ivan.miljenovic at gmail.com
Wed Jul 21 01:41:18 EDT 2010
On 21 July 2010 15:28, Richard O'Keefe <ok at cs.otago.ac.nz> wrote:
> I'm giving some lectures this week about how to _read_ programs,
> and I've had some things to say about JavaDoc and wondered whether
> to show some examples of Haddock.
> I took a certain library that has been mentioned recently in
> this mailing list. (I shall not identify it. The author deserves
> praise for his/her contribution, not a public mauling, and the
> reason for the message is that that package is not unusual.) The
> reason I chose it was that I thought "actually, >>I<< should learn
> how to use that, never mind the students."
> Upon looking at the Haddock web page,
> - reaction one "this is pretty flashy".
> - reaction two, "but WHERE IS THE DOCUMENTATION?"
These are good points and I agree with the rest of your email as well
(which I've removed for the sake of brevity).
However, I would like to offer two qualifiers that I myself have found
when writing documentation for my own libraries:
* When writing the code, it's obvious what it does; as such you may
think any documentation you may offer is trivial (down the track,
* The author is familiar with a library; as such it may not be obvious
what extra documentation could be needed. As such, if you're a user
of a library and you think it's documentation could be improved, maybe
try telling the maintainer that (this kind of prompting is why I
bothered to make a website for my graphviz library).
As a kind of a wishlist, having more markup support would possibly
improve the quality of documentation (rather than being limited to
normal text, monospace text and italic text; I've often times wanted
to make something bold in my Haddock documentation to emphasise it but
alas Haddock doesn't support it).
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
More information about the Haskell-Cafe