Thanks for the feedback. The original docs can be found here ( http://hackage.haskell.org/package/xhtml-3000.2.0.1 ). The changes I added at this point are exclusively in the main description of the Text.XHtml, Text.XHtml.Table, Text.XHtml.Strict, Text.XHtml.Transitional and Text.XHtml.Frameset modules. For the Strict, Transitional, and Frameset modules the only changes from the original is a blurb about checking the main Text.XHtml package for detailed documentation. As for tutorial.happstack.com, no, I don't think that's an example of a "bad tutorial", nor was I complaining that the tutorials available for Haskell are in general bad. My complaint is more that the tutorials can only really be responsible for covering so much material at which point the core documentation (either the auto-generated stuff on hackage, or some other source that's mostly non-existent right now) needs to take up the slack. Text.XHtml is relatively simple, so I was able to provide the kind of documentation it needs directly in the haddock, but for larger non-trivial libraries we really need some kind of standardized location for documentation. Ideally wherever that is should also be intergrated into hackage somehow, as hackage is where most newbies are going to go looking for packages, and the documentation of said packages. That being said, there's currently discussion going on in the other mailing lists about modifications to Hackage to add better support for documentation in general, and user contributed documentation in particular, so maybe it's just a matter of time. -R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat. On Tue, Apr 13, 2010 at 14:51, Thomas Hartman <thomashartman1@googlemail.com

wrote:

Hi Kyle,

On the whole I am always thrilled when someone works to improve the haskell docu, particularly in the web space.

I am the author of tutorial.happstack.com, which I admit might be an example of the type of "bad" tutorials you write of, which nevertheless fill a necessary gap during documentation coallescence.

The reason I didn't give you any feedback is there wasn't an easy/fast way for me to see what changes you had made, other than flipping back and forth from your docu to the original docu, and I'm not even sure where the existing docu is -- hackage I suppose.

If you had used github or (plug) patch-tag, you might have gotten more feedback, or even if you had just (re)stated the type of changes you had made.

Anyway thank you for working to improve the state of haskell on web docu, and of course, contribute back to the xhtml maintainers.

Cheers, thomas.

On Tue, Apr 13, 2010 at 6:56 AM, Kyle Murphy <orclev@gmail.com> wrote:

...

I haven't received any response on this at all so far, which I'm not sure how to interpret. Does everyone think I should submit the updated documentation to the maintainer of the xhtml package, or is there some issue someone would have with seeing these changes in the official distribution? I'm also not sure I'm completely done updating the docs, I'd like to see some better documentation on the actual functions themselves as well, and I'll probably do that before submitting it as a patch.

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

On Sat, Apr 10, 2010 at 03:16, Kyle Murphy <orclev@gmail.com> wrote:

...

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 updated haddock at http://tenletters.org/haddock/index.html

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.

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

On Fri, Apr 9, 2010 at 15:02, Kyle Murphy <orclev@gmail.com> wrote:

...

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.

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.

-R. Kyle Murphy -- Curiosity was framed, Ignorance killed the cat.

On Fri, Apr 9, 2010 at 14:36, Gour <gour@gour-nitai.com> wrote:

...

On Fri, 9 Apr 2010 14:07:28 -0400

...

>>>>> "Kyle" == Kyle Murphy wrote:

Kyle> The next highest level of documentation, what's severely lacking Kyle> in the Haskell community in general, and the web development Kyle> community in particular, is the in depth documentation for the Kyle> libraries/frameworks. These documents aren't quite tutorials, Kyle> but they go beyond just telling you the minimal information you Kyle> need to use a function. This sort of document would typically Kyle> have a section for each of the major use cases of your Kyle> framework/library, and possibly a few brief code snippets Kyle> showing how you go about doing particular things. For instance, Kyle> in the Text.XHTML package, this document would most likely list Kyle> the various functions for generating html elements like br, as Kyle> well as have a section talking about the attribute op (!), the Kyle> Html concatination op (+++), and the Html nesting op (<<), and Kyle> provide examples of how to construct a few example pages. It's Kyle> this level of documentation that's really missing, and where Kyle> most people would head to once they finish following along on Kyle> some tutorial.

If we consider that Django is nicely documented and can be used as example, do you think about stuff called 'topic guides' listed at

http://docs.djangoproject.com/en/dev/intro/whatsnext/#intro-whatsnext

i.e. something in between tutorial and API reference?

Here is blog post about it:

http://jacobian.org/writing/great-documentation/what-to-write/

Kyle> As a final thought, haddock itself might even be leveraged to Kyle> provide this higher level documentation, it certainly has the Kyle> capability of doing so, it just generally isn't used in that

way.

...

Kyle> The brief summary most people put at the top of the generated Kyle> haddock, which usually consists of a one or two sentence Kyle> description of what the library provides, could instead be used Kyle> to provide details of all the use cases, and links to the Kyle> appropiate pieces of documentation.

Long ago I was suggesting on 'cafe' that it would be nice if the haddock documentation would have some 'examples of usage', but it looks it is too much and we are still far from it...

Sincerely, Gour

--

Gour | Hlapicina, Croatia | GPG key: F96FF5F6 ----------------------------------------------------------------

_______________________________________________ web-devel mailing list web-devel@haskell.org http://www.haskell.org/mailman/listinfo/web-devel

_______________________________________________ web-devel mailing list web-devel@haskell.org http://www.haskell.org/mailman/listinfo/web-devel

-- Need somewhere to put your code? http://patch-tag.com Want to build a webapp? http://happstack.com