[web-devel] Re: The state of documentation

[Kyle Murphy]

On Fri, Apr 9, 2010 at 13:04, Gour <gour at gour-nitai.com> wrote:

> OK. Let's wait that Yesod becomes more mature, then we'll evaluate it
> again.
>

Fair enough.


> Well, I agree it's not easy to put ineself in another's shoes, but
> here lies the difference. ;)
>

>
Michael> As far as we're concerned, our code is beautiful, elegant,
> Michael> simple and self-documenting (until we look at it again six
> Michael> months later).
>
> :-)
>
> Michael> We really need an outside voice to tell us what's lacking.
>
> Simple tutorials to get us going. Have you seen the Django tutorial
> written in several parts?
>
> Michael> So instead of saying "fizzbuzz has no documentation," maybe
> Michael> say "I saw the fizzbuzz tutorial on creating foobars, but I
> Michael> couldn't figure out how to extend that for wibbles. Could you
> Michael> write a tutorial for that?"
>
> Well, at the moment I am playing with Hakyll and can just recommend
> every library writer to check Hakyll's tutorials at
>
> http://jaspervdj.be/hakyll/tutorials.html
>
> Psychologically it is very encouraging to be provided with few simple
> steps and achieve something instead of starring at the
> Haddock-generated docs only.
>
> Even the Haskell language (which is not at all simple) has "Haskell
> in 5 steps" & "Learn Haskell in 10 minutes" tutorials.
>
> One may say it's kind of cheating, but if the easy introductory
> material sparks enough interest in the noob user, there is good chance
> that he/she will investigate further.
>

The problem is really that there's multiple levels of documentation. At the
lowest, and least "user friendly" you've got the haddock which isn't much
more than a collection of function signatures. It assumes that if you're
reading it, you're already more or less familiar with the framework and how
to go about doing what you want. The next highest level of documentation,
what's severely lacking in the Haskell community in general, and the web
development community in particular, is the in depth documentation for the
libraries/frameworks. These documents aren't quite tutorials, but they go
beyond just telling you the minimal information you need to use a function.
This sort of document would typically have a section for each of the major
use cases of your framework/library, and possibly a few brief code snippets
showing how you go about doing particular things. For instance, in the
Text.XHTML package, this document would most likely list the various
functions for generating html elements like br, as well as have a section
talking about the attribute op (!), the Html concatination op (+++), and the
Html nesting op (<<), and provide examples of how to construct a few example
pages. It's this level of documentation that's really missing, and where
most people would head to once they finish following along on some tutorial.
If all the libraries you used in your tutorials provided this level of
documentation all you would need to do in your tutorial is to mention which
libraries you used, and if you're feeling generous provide a link to their
documentation. Unfortunately, that's not the state that the vast majority of
Haskell libraries are in, there being only haddock, and if you're lucky a
tutorial or two. This unfortunately puts the tutorial writers in a rather
awkward position where even if the main framework, happs lets say, is well
documented, all the support libraries that are necessary to put together a
working tutorial aren't, and thus confuse newbies looking to use the
tutorial.

One solution, although a rather bad one, is for the tutorial writers to help
fill in the missing documentation, either directly, or by writing yet more
tutorials to document the support libraries. This is bad for a number of
reasons, not the least of which is that a tutorial isn't the place to
document huge swaths of a framework, which is something best left to the
intermediate documentation mentioned previously (with the haddock being used
to document the minute details, and the not often visited cranies). The
other reason this is a bad solution is that as an example, the creator of
Yesod, who decides to write a tutorial on using it, should not then be
obliged to create documentation for lets say HStringTemplate just because he
happens to need it for his tutorial.

The better long term solution is to encourage some kind of detailed
documentation to be produced for the majority of Haskell libraries. I'm
hesitant to say it should be required, as obviously such a requirement might
discourage people from bothering to share the work they do, but at the same
time something needs to be done to encourage documentation beyond the simple
haddock that's used as the sole documentation of the vast majority of
libraries (many of which don't even provide anything in the haddock besides
the function signature, something that's easy enough to get from ghci).

As a final thought, haddock itself might even be leveraged to provide this
higher level documentation, it certainly has the capability of doing so, it
just generally isn't used in that way. The brief summary most people put at
the top of the generated haddock, which usually consists of a one or two
sentence description of what the library provides, could instead be used to
provide details of all the use cases, and links to the appropiate pieces of
documentation. As an example, consider this documentation of the Java
Pattern class (
http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html ). If
the majority of Haskell libraries contained as thorough documentation as
that in their haddock, you'd rarely even need to consult a tutorial or other
documentation.

-R. Kyle Murphy
--
Curiosity was framed, Ignorance killed the cat.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/web-devel/attachments/20100409/86b6ead4/attachment.html