I managed to find some time to put together an example update of the documentation for xhtml package with the sorts of changes I'd like to see applied to as much of hackage as possible.you can find the udated haddock at <a href="http://tenletters.org/haddock/index.html">http://tenletters.org/haddock/index.html</a><br>
<br>Depending on the feedback I get on this updated documentation I might try to get in touch with the xhtml maintainer and have my changes merged in to the official repository. Let me know what you guys think.<br><br clear="all">
-R. Kyle Murphy<br>--<br>Curiosity was framed, Ignorance killed the cat.<br>
<br><br><div class="gmail_quote">On Fri, Apr 9, 2010 at 15:02, Kyle Murphy <span dir="ltr"><<a href="mailto:orclev@gmail.com">orclev@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
That blog post was excellent and fairly well captures the spirit of what I was getting at, although I do disagree somewhat about the auto-generated docs. I don't have any problem with auto-generated docs in and of themselves, assuming that you also insert into that documentation the sort of details discussed in the "topic guides". A great example of this is most of the POD used in Perl modules, where at least the first few paragraphs of documentation are typically devoted to essentially being a "topic guide" for that module. I think what she was really complaining about in that post is exactly the situation we have in hackage currently where there is for all intents and purpose absolutely no documentation provided for the vast majority of libraries beyond the automatically generated signatures and the odd sentence or two.<br>
<br>Something I'd like to see become common in haddock is for instance, a good general description, with references to sub-modules in the main module of a package. Each sub-module would then function as a topic guide for the features of that module, with the specific API details contained in the function descriptions. If I have some time this weekend maybe I'll pull down the source for Text.XHTML, and try to update its documentation to provide an example of what I'm getting at.<div class="im">
<br>
<br clear="all">-R. Kyle Murphy<br>--<br>Curiosity was framed, Ignorance killed the cat.<br>
<br><br></div><div class="gmail_quote"><div><div></div><div class="h5">On Fri, Apr 9, 2010 at 14:36, Gour <span dir="ltr"><<a href="mailto:gour@gour-nitai.com" target="_blank">gour@gour-nitai.com</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div><div></div><div class="h5">
On Fri, 9 Apr 2010 14:07:28 -0400<br>
>>>>>> "Kyle" == Kyle Murphy wrote:<br>
<br>
Kyle> The next highest level of documentation, what's severely lacking<br>
Kyle> in the Haskell community in general, and the web development<br>
Kyle> community in particular, is the in depth documentation for the<br>
Kyle> libraries/frameworks. These documents aren't quite tutorials,<br>
Kyle> but they go beyond just telling you the minimal information you<br>
Kyle> need to use a function. This sort of document would typically<br>
Kyle> have a section for each of the major use cases of your<br>
Kyle> framework/library, and possibly a few brief code snippets<br>
Kyle> showing how you go about doing particular things. For instance,<br>
Kyle> in the Text.XHTML package, this document would most likely list<br>
Kyle> the various functions for generating html elements like br, as<br>
Kyle> well as have a section talking about the attribute op (!), the<br>
Kyle> Html concatination op (+++), and the Html nesting op (<<), and<br>
Kyle> provide examples of how to construct a few example pages. It's<br>
Kyle> this level of documentation that's really missing, and where<br>
Kyle> most people would head to once they finish following along on<br>
Kyle> some tutorial.<br>
<br>
If we consider that Django is nicely documented and can be used as<br>
example, do you think about stuff called 'topic guides' listed at<br>
<br>
<a href="http://docs.djangoproject.com/en/dev/intro/whatsnext/#intro-whatsnext" target="_blank">http://docs.djangoproject.com/en/dev/intro/whatsnext/#intro-whatsnext</a><br>
<br>
i.e. something in between tutorial and API reference?<br>
<br>
Here is blog post about it:<br>
<br>
<a href="http://jacobian.org/writing/great-documentation/what-to-write/" target="_blank">http://jacobian.org/writing/great-documentation/what-to-write/</a><br>
<br>
Kyle> As a final thought, haddock itself might even be leveraged to<br>
Kyle> provide this higher level documentation, it certainly has the<br>
Kyle> capability of doing so, it just generally isn't used in that way.<br>
Kyle> The brief summary most people put at the top of the generated<br>
Kyle> haddock, which usually consists of a one or two sentence<br>
Kyle> description of what the library provides, could instead be used<br>
Kyle> to provide details of all the use cases, and links to the<br>
Kyle> appropiate pieces of documentation.<br>
<br>
Long ago I was suggesting on 'cafe' that it would be nice if the<br>
haddock documentation would have some 'examples of usage', but it<br>
looks it is too much and we are still far from it...<br>
<div><div></div><div><br>
<br>
Sincerely,<br>
Gour<br>
<br>
--<br>
<br>
Gour | Hlapicina, Croatia | GPG key: F96FF5F6<br>
----------------------------------------------------------------<br>
</div></div><br></div></div>_______________________________________________<br>
web-devel mailing list<br>
<a href="mailto:web-devel@haskell.org" target="_blank">web-devel@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/web-devel" target="_blank">http://www.haskell.org/mailman/listinfo/web-devel</a><br>
<br></blockquote></div><br>
</blockquote></div><br>