[web-devel] Re: The state of documentation

[Gour]

On Fri, 9 Apr 2010 08:06:08 -0700
>>>>>> "Michael" == Michael Snoyman wrote:

Michael> I can't speak for others, but I personally don't have a
Michael> problem investing in documentation on my one-man-show
Michael> libraries. In the specific case of Yesod, I *know* it's going
Michael> to have some major changes in the next release, so it's not
Michael> worth it right now.

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

Michael> In general, I think the problem for library writers is that-
Michael> since *we* wrote the code- we don't know what's confusing
Michael> about it. 

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.


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/bbd0466c/signature.bin