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.
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
