+1 for Heinrich Apfelmus's suggestion of cookbook recipes.
In other language communities I see a lot of "quickstart" guides designed to
help someone get up and running without a full understanding of what they're
doing, presumably with the hope that once they get started it will provide
the motivation to keep learning. But admittedly, and for good reason,
learning the how without the why seems to run counter to the general
mentality of the Haskell community.
For widely used libraries it'd be nice to a see a supporting wiki page
broken into sections like conceptual overview, how to navigate the API if
it's extensive, tutorials, and cookbook recipes. Motivating the community to
contribute supporting documentation could alleviate some of the burden for
library writers. Frequently updated and extensive community docs can also
help newcomers decide which library to start with for a given task, rather
than relying purely on Hackage descriptions. I'm slowly assembling
supporting docs of this kind for the libraries I use the most, and if anyone
is working on something similar I'm happy to help by trying out the
tutorials and giving feedback.
Thanks!
Eric
On Tue, Sep 13, 2011 at 2:15 PM, 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
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe