[web-devel] Re: The state of documentation

[Gour]

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
----------------------------------------------------------------
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
Url : http://www.haskell.org/pipermail/web-devel/attachments/20100409/763862ee/signature.bin