<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> </head> <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. Here is the link: <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> Below, for your convenience, is the complete text copy-pasted in. Thanks, -Everett <h2>How To Design Documentation</h2> We’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. 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: <ul> <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’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.</li> </ul> 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. </body> </html>