Thanks for the feedback. The original docs can be found here <br>( <a href="http://hackage.haskell.org/package/xhtml-3000.2.0.1">http://hackage.haskell.org/package/xhtml-3000.2.0.1</a> ). The <br>changes I added at this point are exclusively in the main description <br>
of the Text.XHtml, Text.XHtml.Table, Text.XHtml.Strict, <br>Text.XHtml.Transitional and Text.XHtml.Frameset modules. For the <br>Strict, Transitional, and Frameset modules the only changes from the <br>original is a blurb about checking the main Text.XHtml package for <br>
detailed documentation.<br><br>As for <a href="http://tutorial.happstack.com/" target="_blank">tutorial.happstack.com</a>, no, I don't think that's an example of a <br>"bad tutorial", nor was I complaining that the tutorials available<br>
for Haskell are in general bad. My complaint is more that the <br>tutorials can only really be responsible for covering so much<br>material at which point the core documentation (either the <br>auto-generated stuff on hackage, or some other source that's mostly<br>
non-existent right now) needs to take up the slack.<br><br>Text.XHtml is relatively simple, so I was able to provide the kind of<br>documentation it needs directly in the haddock, but for larger <br>non-trivial libraries we really need some kind of standardized<br>
location for documentation. Ideally wherever that is should also be<br>intergrated into hackage somehow, as hackage is where most newbies<br>are going to go looking for packages, and the documentation of said<br>packages.<br>
<br>That being said, there's currently discussion going on in the other<br>mailing lists about modifications to Hackage to add better support<br>for documentation in general, and user contributed documentation<br>in particular, so maybe it's just a matter of time.<br>
<br clear="all">-R. Kyle Murphy<br>--<br>Curiosity was framed, Ignorance killed the cat.<br>
<br><br><div class="gmail_quote">On Tue, Apr 13, 2010 at 14:51, Thomas Hartman <span dir="ltr"><<a href="mailto:thomashartman1@googlemail.com">thomashartman1@googlemail.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;">
Hi Kyle,<br>
<br>
On the whole I am always thrilled when someone works to improve the<br>
haskell docu, particularly in the web space.<br>
<br>
I am the author of <a href="http://tutorial.happstack.com" target="_blank">tutorial.happstack.com</a>, which I admit might be an<br>
example of the type of "bad" tutorials you write of, which<br>
nevertheless fill a necessary gap during documentation coallescence.<br>
<br>
The reason I didn't give you any feedback is there wasn't an<br>
easy/fast way for me to see what changes you had made, other than<br>
flipping back and forth from your docu to the original docu, and I'm<br>
not even sure where the existing docu is -- hackage I suppose.<br>
<br>
If you had used github or (plug) patch-tag, you might have gotten<br>
more feedback, or even if you had just (re)stated the type of changes<br>
you had made.<br>
<br>
Anyway thank you for working to improve the state of haskell on web<br>
docu, and of course, contribute back to the xhtml maintainers.<br>
<br>
Cheers, thomas.<br>
<div><div></div><div class="h5"><br>
<br>
<br>
On Tue, Apr 13, 2010 at 6:56 AM, Kyle Murphy <<a href="mailto:orclev@gmail.com">orclev@gmail.com</a>> wrote:<br>
> I haven't received any response on this at all so far, which I'm not sure<br>
> how to interpret. Does everyone think I should submit the updated<br>
> documentation to the maintainer of the xhtml package, or is there some issue<br>
> someone would have with seeing these changes in the official distribution?<br>
> I'm also not sure I'm completely done updating the docs, I'd like to see<br>
> some better documentation on the actual functions themselves as well, and<br>
> I'll probably do that before submitting it as a patch.<br>
><br>
> -R. Kyle Murphy<br>
> --<br>
> Curiosity was framed, Ignorance killed the cat.<br>
><br>
><br>
> On Sat, Apr 10, 2010 at 03:16, Kyle Murphy <<a href="mailto:orclev@gmail.com">orclev@gmail.com</a>> wrote:<br>
>><br>
>> I managed to find some time to put together an example update of the<br>
>> documentation for xhtml package with the sorts of changes I'd like to see<br>
>> applied to as much of hackage as possible. You can find the updated haddock<br>
>> at <a href="http://tenletters.org/haddock/index.html" target="_blank">http://tenletters.org/haddock/index.html</a><br>
>><br>
>> Depending on the feedback I get on this updated documentation I might try<br>
>> to get in touch with the xhtml maintainer and have my changes merged in to<br>
>> the official repository. Let me know what you guys think.<br>
>><br>
>> -R. Kyle Murphy<br>
>> --<br>
>> Curiosity was framed, Ignorance killed the cat.<br>
>><br>
>><br>
>> On Fri, Apr 9, 2010 at 15:02, Kyle Murphy <<a href="mailto:orclev@gmail.com">orclev@gmail.com</a>> wrote:<br>
>>><br>
>>> That blog post was excellent and fairly well captures the spirit of what<br>
>>> I was getting at, although I do disagree somewhat about the auto-generated<br>
>>> docs. I don't have any problem with auto-generated docs in and of<br>
>>> themselves, assuming that you also insert into that documentation the sort<br>
>>> of details discussed in the "topic guides". A great example of this is most<br>
>>> of the POD used in Perl modules, where at least the first few paragraphs of<br>
>>> documentation are typically devoted to essentially being a "topic guide" for<br>
>>> that module. I think what she was really complaining about in that post is<br>
>>> exactly the situation we have in hackage currently where there is for all<br>
>>> intents and purpose absolutely no documentation provided for the vast<br>
>>> majority of libraries beyond the automatically generated signatures and the<br>
>>> odd sentence or two.<br>
>>><br>
>>> Something I'd like to see become common in haddock is for instance, a<br>
>>> good general description, with references to sub-modules in the main module<br>
>>> of a package. Each sub-module would then function as a topic guide for the<br>
>>> features of that module, with the specific API details contained in the<br>
>>> function descriptions. If I have some time this weekend maybe I'll pull down<br>
>>> the source for Text.XHTML, and try to update its documentation to provide an<br>
>>> example of what I'm getting at.<br>
>>><br>
>>> -R. Kyle Murphy<br>
>>> --<br>
>>> Curiosity was framed, Ignorance killed the cat.<br>
>>><br>
>>><br>
>>> On Fri, Apr 9, 2010 at 14:36, Gour <<a href="mailto:gour@gour-nitai.com">gour@gour-nitai.com</a>> wrote:<br>
>>>><br>
>>>> 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>
>>>><br>
>>>><br>
>>>> Sincerely,<br>
>>>> Gour<br>
>>>><br>
>>>> --<br>
>>>><br>
>>>> Gour | Hlapicina, Croatia | GPG key: F96FF5F6<br>
>>>> ----------------------------------------------------------------<br>
>>>><br>
>>>> _______________________________________________<br>
>>>> web-devel mailing list<br>
>>>> <a href="mailto:web-devel@haskell.org">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>
>>><br>
>><br>
><br>
><br>
> _______________________________________________<br>
> web-devel mailing list<br>
> <a href="mailto:web-devel@haskell.org">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>
><br>
<br>
<br>
<br>
</div></div><font color="#888888">--<br>
Need somewhere to put your code? <a href="http://patch-tag.com" target="_blank">http://patch-tag.com</a><br>
Want to build a webapp? <a href="http://happstack.com" target="_blank">http://happstack.com</a><br>
</font></blockquote></div><br>