[racket-dev] Racket documentation

On Tue, Sep 21, 2010 at 1:14 PM, Everett Morse <webj2 at unoc.net> wrote:
> 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 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.

What do you think is missing from these tutorials:

http://docs.racket-lang.org/quick/index.html

http://docs.racket-lang.org/continue/index.html

http://docs.racket-lang.org/more/index.html

In particular, Quick tries to present the essence of the languages.
Maybe the problem is that since we are PL researchers, we have a more
refined opinion about the "language" versus the "libraries" so our
tutorials don't go too deep in the libraries.

> 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.

My gut tells me that this is needed in PHP because it as more ad-hoc
cases rather than the elegant purity of Racket. My gut also tells me
that this is a biased position.

> 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.

We need more examples in the docs. It's easy to add them and I will
help anyone who wants to get involved.

> 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.

This is a good idea, but I think it is a symptom of the one-page per
function, whereas in Racket they are listed together with related
ones.

> 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).

See above with the ad-hoc grossness of PHP.

> 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.

Jay

-- 
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://teammccarthy.org/jay

"The glory of God is Intelligence" - D&C 93