[racket-dev] Racket documentation

I had some thoughts about Racket's documentation compared to PHP's last 
night, so this morning I wrote up a blog post about it.

Here is the link:
http://www.neptic.com/blog/2010/09/how-to-design-documentation/

Below, for your convenience, is the complete text copy-pasted in.

Thanks,
-Everett



    How To Design Documentation

We've been using a programming language called Racket 
<http://www.racket-lang.org> in our lab, and one of the new guys is 
constantly complaining about its documentation. Everyone agrees, but we 
argued a bit about what language has good documentation. Here is one 
that I missed in that discussion; I will explain why PHP is a model citizen.

*Background*

I learned to program at the age of ten from books on BASIC Level II 
using a Radio Shack TRS-80 (black and white). At twelve, my dad gave me 
a book on Java, but it was written to help a C programmer learn Java. So 
I read a book on C for BASIC programmers, then immediately dumped C and 
learned Java. I read many more programming books after that, mostly 
about Java. The net result is that by my senior year in HS I had a solid 
background in Java with basic understanding of C, C++, and Javascript.

*How I learned PHP*

At that point I heard about PHP as a website programming language, and 
decided to learn it. Whereas with Java, C, and BASIC I had read books, 
with Javascript I had learned rudimentarily by just copy-paste-edit. So 
I began with copy-paste-edit on PHP too. But I also read one of those 
"Getting Started" / "Five-Minute" tutorials, which helped because of my 
background in Java.

That got me started, but from then on I constantly referred back to the 
PHP online documentation, and over the course of one job (about eight 
months) I gained a solid understanding of PHP just from using it with 
the documentation.

*What Racket Has*

With Racket, no short tutorial is going to work because it has a LISP 
(and Scheme) functional programming background that is foreign to most 
new programmers and many experienced ones. It does, however, have a good 
sized guide that can get someone into the language well enough. They 
also have searchable, browsable documentation of every function in the 
entire API. However, that API documentation, while complete, is usually 
so cryptic or vague that it is useless. I'm sure if you understood 
Racket well it would all make sense, but it does not help a beginner get 
better.

*What PHP Does*

PHP has a whole page for every function in its API. The page describes 
the function parameters, lists all the options, and describes the 
possible output. But here is what more it does:

    * It describes corner cases, like what happens when empty string is
      passed in, or what happens if the right environment is not present.
    * It gives examples for almost every function. It is often easier
      and faster to skim the function description, then read the
      examples to learn how it is used. This makes more sense than
      trying to parse some description, especially easier than parsing
      the grammar-like definitions of Racket functions.
    * It lists related functions. You may be looking for something
      similar to the function you found. This listing helps you compare
      similar functions and hone in on the one you really want.
    * Occasionally it warns (with appropriate font and colors) about
      common gotchas, like when something has changed from one API
      version to another (e.g. a function now returns false on failure
      instead of -1), or when some environment needs to be set up right
      (e.g. setting a timezone before calling the date function, it even
      tells you what function sets the timezone).
    * Finally, at the bottom of the page is user comments. Here friendly
      people can ask all the common dumb user questions that help out
      everyone else who also had the same dumb question. (So dumb the
      documenters didn't think it worth explaining.) People also tend to
      arrive at the same place looking for certain functionality, and
      the comments may point in the right direction, or else they may
      contain an implementation of a new function that adds the
      functionality people might be looking for but that isn't in the
      API already. Users gradually approach reasonable information, and
      thus the comments become a good source. They even explore
      potential bugs or use cases beyond the examples and corner cases.

On the whole, from reading PHP documentation one can quickly understand 
a function with its descriptions and examples, hone in on the function 
one really wants with lists of similar functions, warnings, and user 
comments, and gain a better understanding of tricky or missing features 
with user discussion. This results in a community that can work very 
efficiently even when they don't already know (or don't remember) the 
function they need or details of how it works. Thus many people can 
quickly learn how to use PHP.

*Conclusion*

Prior to comparing Racket to PHP, I always thought it would be nice to 
have examples given for every function. I believe that in addition to 
this, there should be a user comments section. This section will 
eventually provide data on common pitfalls, similar functions, desired 
functionality, etc. that the core team can take into account both to 
improve their documentation and the Racket API itself.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/dev/archive/attachments/20100921/0fe9fd59/attachment.html>