[Haskell-cafe] On documentation

[Ivan Miljenovic]

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,
however...).

* 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
IvanMiljenovic.wordpress.com