[plt-scheme] documentation feature requests

Crutches are often quite useful! :-)

Minimal examples shouldn't add much clutter, and a minimal example can  
establish a base line of understanding even when more reading would be  
necessary to do anything fancier.

I mentioned the use of examples in the Processing documentation --  
here's a link: http://processing.org/reference/ . You'll see that  
almost every procedure is introduced with a simple example, sometimes  
just a single line (although in some cases it has to be quite a bit  
longer). One can often just glance at the example and know how to use  
the procedure in the simplest cases, without reading anything else.

There are already a few examples of the sort that I'm talking about in  
the PLT documentation -- for example I like the examples for build- 
list and for several of the other procedures in section 3.9. What I  
was hoping to encourage was the inclusion of such example more  
uniformly throughout the documentation.

  -Lee




On Nov 15, 2009, at 5:58 PM, Neil Van Dyke wrote:

> I actually find writing examples for procedures to be relatively  
> fun, as API documentation goes.  (Though not as much fun as it used  
> to be, now that I'm targeting so-so HTML, rather than nicely typeset  
> PDF with my pretty TeXinfo "@result{}" arrow and everything.)
>
> I can also see validity of arguments, e.g., that lots of little  
> examples often clutter the documentation unnecessarily, and that  
> such examples are often used as crutches in lieu of understanding  
> the language, library, or problem domain.
>
> Also note that examples won't necessarily avert you having to look  
> around at bits of documentation.  Below is an example from one of my  
> libraries.  You could use it as a model for how to turn a CSV file  
> into SXML, but that doesn't tell you how to transform the SXML, nor  
> pick values out of it, nor write it out as XML, etc.  Such things  
> are not within the scope of the documentation of this procedure nor  
> this library.
>
>> For example, given a CSV-format file friends.csv that has the  
>> contents:
>>
>> Binoche,Ste. Brune,33-1-2-3
>> Posey,Main St.,555-5309
>> Ryder,Cellblock 9,
>>
>> with elements not given, the result is:
>>
>>  (csv->sxml (open-input-file "friends.csv"))
>>  ==>
>>  (*TOP*
>>   (row (col-0 "Binoche") (col-1 "Ste. Brune")  (col-2 "33-1-2-3"))
>>   (row (col-0 "Posey")   (col-1 "Main St.")    (col-2 "555-5309"))
>>   (row (col-0 "Ryder")   (col-1 "Cellblock 9") (col-2 "")))
>>
>> With elements given, the result is like:
>>
>>  (csv->sxml (open-input-file "friends.csv")
>>             'friend
>>             '(name address phone))
>>  ==>
>>  (*TOP* (friend (name    "Binoche")
>>                 (address "Ste. Brune")
>>                 (phone   "33-1-2-3"))
>>         (friend (name    "Posey")
>>                 (address "Main St.")
>>                 (phone   "555-5309"))
>>         (friend (name    "Ryder")
>>                 (address "Cellblock 9")
>>                 (phone   "")))
>
> -- 
> http://www.neilvandyke.org/

--
Lee Spector, Professor of Computer Science
School of Cognitive Science, Hampshire College
893 West Street, Amherst, MA 01002-3359
lspector at hampshire.edu, http://hampshire.edu/lspector/
Phone: 413-559-5352, Fax: 413-559-5438

Check out Genetic Programming and Evolvable Machines:
http://www.springer.com/10710 - http://gpemjournal.blogspot.com/