Stephen Tetley wrote:
Replying to someone's compliant in the first section:
Malcolm Wallace and Colin Runciman's ICFP99 paper functioned well as a
tutorial for HaXml when I used it - maybe it is a bit out of date now?
HaXml is hardly a dire case.
... for the right audience. I guess the point is that the person
complaining could not understand the existing documentation. Quote:
"This type of documentation may seem to “fall out” from a
mathematically-oriented understanding of the library (such as haxml’s
combinator scheme, or the concept of “lenses” in fclabels), but an
application programmer does not have time to work through proofs of lens
properties and then figure out what they might be good for in a program.
Instead, the application programmer needs cookbook-style documentation
to get something up and running, and then s/he can come to understand
and make use of the underlying math."
I'm not sure whether it's the job of library documentation to teach
mathematical understanding, but cookbook-style examples seem very
valuable to me. For instance, I think that the Happstack tutorial
http://happstack.com/docs/crashcourse/index.html
is excellent in this regard.
(Personally, a good method for writing this kind of stuff is to assume
that the reader has almost zero attention span. Then, I am forced to
communicate the most useful points in the first few paragraphs, because
my hypothetical reader probably won't read any further than that. Of
course, the resulting text will be very useful to readers with a high
attention span, too.)
Best regards,
Heinrich Apfelmus
--
http://apfelmus.nfshost.com
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
