+1 for Heinrich Apfelmus&#39;s suggestion of cookbook recipes. <br><br>In other language communities I see a lot of &quot;quickstart&quot; guides designed to help someone get up and running without a full understanding of what they&#39;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.<br>
<br>For widely used libraries it&#39;d be nice to a see a supporting wiki page broken into sections like conceptual overview, how to navigate the API if it&#39;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&#39;m slowly assembling supporting docs of this kind for the libraries I use the most, and if anyone is working on something similar I&#39;m happy to help by trying out the tutorials and giving feedback.<br>
<br>Thanks!<br>Eric<br><br><br><br><div class="gmail_quote">On Tue, Sep 13, 2011 at 2:15 PM, Malcolm Wallace <span dir="ltr">&lt;<a href="mailto:malcolm.wallace@me.com">malcolm.wallace@me.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im"><br>
On 13 Sep 2011, at 18:59, Michael Orlitzky wrote:<br>
<br>
&gt;&gt; Malcolm Wallace and Colin Runciman&#39;s ICFP99 paper functioned well as a<br>
&gt;&gt; tutorial for HaXml when I used it - maybe it is a bit out of date now?<br>
&gt;&gt; HaXml is hardly a dire case.<br>
&gt;<br>
&gt; The paper is out-of-date, so it&#39;s worse than useless: you&#39;ll waste your<br>
&gt; time figuring out that it&#39;s wrong, and you still won&#39;t know how to do<br>
&gt; anything.<br>
&gt;<br>
&gt; There&#39;s not one single example anywhere that just shows you how to read<br>
&gt; or write a damned XML file.<br>
</div><div class="im">&gt; If there were anything approaching a physical manifestation of HaXml, I<br>
&gt; would&#39;ve strangled it.<br>
<br>
</div>I am the first to admit that HaXml&#39;s documentation is not as good as it could be, and I am sorry that you have had a bad experience.<br>
<br>
One thing I am puzzled about, is just how extremely difficult it must be, to click on &quot;Detailed documentation of the HaXml APIs&quot; from the HaXml homepage, look for a moment until you see &quot;Text.XML.HaXml.Parse&quot; 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.<br>

<br>
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 &quot;Text.XML.HaXml.Pretty&quot; to convert to a Doc, then &quot;Text.PrettyPrint.HughesPJ&quot; to render to a String; or alternatively the one-shot conversion in &quot;Text.XML.HaXml.Verbatim&quot;.  Neither module name is as clear as it should be for a beginner, but I can&#39;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.<br>

<br>
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&#39;d like to signpost it better.<br>

<br>
Regards,<br>
<font color="#888888">    Malcolm<br>
</font><div><div></div><div class="h5"><br>
_______________________________________________<br>
Haskell-Cafe mailing list<br>
<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
</div></div></blockquote></div><br>