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

[Eric Rasmussen]

+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 <malcolm.wallace at me.com>wrote:

>
> 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 at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20110913/a6566eff/attachment.htm>