<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <meta content="text/html; charset=ISO-8859-1"
<body text="#000000" bgcolor="#ffffff">
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.<br>
Here is the link:<br>
<a class="moz-txt-link-freetext" href="http://www.neptic.com/blog/2010/09/how-to-design-documentation/">http://www.neptic.com/blog/2010/09/how-to-design-documentation/</a><br>
Below, for your convenience, is the complete text copy-pasted in.<br>
<h2>How To Design Documentation</h2>
<p>We&#8217;ve been using a programming language called <a
 title="Racket programming language" href="http://www.racket-lang.org">Racket</a>
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.</p>
<p>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
<p><strong>How I learned PHP</strong></p>
<p>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 &#8220;Getting Started&#8221; / &#8220;Five-Minute&#8221; tutorials, which
helped because of my background in Java.</p>
<p>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.</p>
<p><strong>What Racket Has</strong></p>
<p>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&#8217;m sure if you
understood Racket well it would all make sense, but it does not help a
beginner get better.</p>
<p><strong>What PHP Does</strong></p>
<p>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:</p>
  <li>It describes corner cases, like what happens when empty string is
passed in, or what happens if the right environment is not present.</li>
  <li>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.</li>
  <li>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.</li>
  <li>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).</li>
  <li>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&#8217;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&#8217;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.</li>
<p>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&#8217;t already know (or
don&#8217;t remember) the function they need or details of how it works. Thus
many people can quickly learn how to use PHP.</p>
<p>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.</p>