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

[Malcolm Wallace]

On 13 Sep 2011, at 18:59, Michael Orlitzky wrote:

>> 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.
> 
> The paper is out-of-date, so it's worse than useless: you'll waste your
> time figuring out that it's wrong, and you still won't know how to do
> anything.
> 
> There's not one single example anywhere that just shows you how to read
> or write a damned XML file.
> If there were anything approaching a physical manifestation of HaXml, I
> would've strangled it.

I am the first to admit that HaXml's documentation is not as good as it could be, and I am sorry that you have had a bad experience.

One thing I am puzzled about, is just how extremely difficult it must be, to click on "Detailed documentation of the HaXml APIs" from the HaXml homepage, look for a moment until you see "Text.XML.HaXml.Parse" in the list of modules, click on it, and find, right at the top of the page, a function that parses a String into an XML document tree.

It is absolutely true that finding the reverse conversion (XML tree to String) is more obscure, being either the two-stage process of first using "Text.XML.HaXml.Pretty" to convert to a Doc, then "Text.PrettyPrint.HughesPJ" to render to a String; or alternatively the one-shot conversion in "Text.XML.HaXml.Verbatim".  Neither module name is as clear as it should be for a beginner, but I can't think of better ones.  Plus, it requires some knowledge of the ecosystem, for instance that pretty-printing is a common technique for producing textual output.

In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up?  Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do.  I have tried writing documentation, but it seems that people do not know how to find, or use it.  Navigating an API you do not know is hard.  I'd like to signpost it better.

Regards,
    Malcolm