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 ----------------------------------------------------------------