On Tue, Sep 21, 2010 at 1:14 PM, Everett Morse <we...@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 <j...@cs.byu.edu> Assistant Professor / Brigham Young University http://teammccarthy.org/jay "The glory of God is Intelligence" - D&C 93 _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev