[Haskell-cafe] Categorized Weaknesses from the State of Haskell 2011 Survey

[Heinrich Apfelmus]

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