[plt-scheme] Additional material for the helpdesk

George, these are some good ideas that you present here, especially 
concerning (1) "one stop shopping"; (2) the way we index into the 
manuals; and (3) user contributions.

Context 1: PLT's DrScheme is not a programming language but an IDE for 
many "dialects" of Scheme. We took the Platonic idea of "Report Scheme" 
to the extreme and provide a whole bunch of Scheme-like languages (and 
others) within DrScheme.

Context 2: The Cookbook is not a PLT-specific book; it just currently 
focuses on PLT Scheme, as the coverpage says. We need to respect this.

So, on to your ideas:

re 1: I really think that we should open up Help Desk so that the 
Cookbook editors can contribute their documentation to our releases. 
Great idea.

This is the closest thing we can do right now for one-stop Info (and 
language integration) until all other Scheme implementors stop working 
on their stuff and begin to contribute to PLT :-) [Note: I consider the 
multitude of Scheme implementations as a disadvantage but also an 
advantage. Like the Internet, "Scheme" will survive because of it, and 
that's good. So this is a joke, just in case someone misses/misreads my 
smiley.]

Having said that, we may wish to consider contributing our 
documentation to the a web site such as Cookbook so that you can enter 
the docs from a single place on the Web, if that's your preference.

re 2: You're right. When a programmer searches in Help Desk, nothing 
but the most relevant information should show up. So you probably 
shouldn't be able to look in Help Desk without having chosen a 
language. The results should be restricted to what applies to your 
language. The results should be ordered according to relevance: 
Cookbook, language manual, etc. And possibly the results should come 
with Google-like excerpts from the doc pages so that you can you can 
choose the most relevant easily.

re 3: I have suggested a user-open book the other day to the internal 
group but the uniform response was "use a wiki." I have two responses 
for now:

- One, we could just direct you to Cookbook where you can already 
contribute as an author. Is this what you want?

- Two, we could create a system like the one for Bug Reports that 
programmers can use to submit editorial comments, which we then (after 
approval) incorporate into the docs automatically. Problem is that such 
documentation could quickly get out-of-date when we upgrade, etc. 
Someone would have to actively edit such user annotations.

I very much like the idea of opening up the docs to our users and 
having them contribute.

Thanks for your proposals. We will discuss this. Happy New Year  -- 
Matthias





On Dec 31, 2005, at 2:05 AM, George Herson wrote:

> --- Corey Sweeney <corey.sweeney at gmail.com> wrote:
>
>> yes, except that instead of "would be", it already
>> is ;) .  For those who
>> havn't seen it, the scheme cookbook can be found at
>> http://schemecookbook.org/Cookbook/TOC , and accepts
>> wiki contributions.
>>
>> Corey
>
> ?? Are you saying that being on the web is close
> enough to being in the Help Desk, or that the scheme
> cookbook is already in the PLT Help Desk?  My
> findings, in case those are needed, are that the Help
> Desk doesn't include the Cookbook:
> Searching on "Case Sensitivity" in the PLT Help Desk
> while using language "Pretty Big", I got matches in
> "Teach Yourself Scheme in Fixnum Days" and "PLT
> MzScheme: Language Manual".  Searching on that string
> in the search field at top right of
> http://schemecookbook.org/, meanwhile, netted the
> helpful
> http://schemecookbook.org/view/Cookbook/CaseSensitivity.
>
> Also, when I click on Language - Choose Language in
> the PLT Help Desk I see a "Manual Search Order" of 28
> documents, none of which is the Cookbook.
>
>
> As to the question of including the Cookbook in the
> Help Desk, I say Perhaps, but it is more important to
> do the reverse: include the Help Desk in the Cookbook,
> to allow one-stop knowledge shopping in support of
> users eager simply to get their work done.  Links to
> the various Scheme manuals incorporated into the
> Cookbook would mainly provide urls for any info that
> we might want to reference either from the main
> Cookbook text or from the various annotations to it.
>
> (Experimenting in the large like this is better to
> done collaboratively on the web than in a nice, stable
> tool like the Help Desk, IMO.)
>
> To take a usage example, let's say you wanted to learn
> more about the difference between eq and eqv.
> Currently, you'd most likely start with searches with
> the PLT Help Desk.  Searching on eqv would return 13
> links:
>
> Teach Yourself Scheme in Fixnum Days
> eqv? in "t-y-scheme"
>
> Revised^5 Report on the Algorithmic Language Scheme
> (eqv? obj1 obj2) in "Equivalence predicates"
> eqv? in "Auxiliary functions"
>
> PLT MzScheme: Language Manual
> eqv? in "Numbers"
> eqv? in "Booleans"
> eqv? in "Structure Utilities"
>
> Intermediate Student with Lambda Language
> eqv? in "eqv?"
>
> Intermediate Student Language
> eqv? in "eqv?"
>
> Inside PLT MzScheme
> eqv? in "Library Functions"
> scheme_eqv in "Library Functions"
>
> Beginning Student with List Abbreviations Language
> eqv? in "eqv?"
>
> Beginning Student Language
> eqv? in "eqv?"
>
> Advanced Student Language
> eqv? in "eqv?"
>
> and a search on eq, many, many more. If you were just
> starting your PLT Scheme studies you might not know
> were to proceed and be sorely tempted to instead (or
> additionally, once confused) post to the mailing list.
>  While this can be collegial and fun, contrast this
> with the efficiency and self-sufficiency of a PHP
> programmer: s/he'd go to a single web page
> (http://www.php.net/manual/en/language.operators.comparison.php)
> and find the official explanation of the workings of
> all the various comparison operators, plus
> cookbook-like user-contributed hints and examples that
> have survived somewhat brutal meritocratic culling
> afforded by the wild popularity of the language, and
> the web.
>
> PLT Scheme, I humbly suggest, needs the same
> command-level pages with examples and user
> annotations, just like http://www.php.net/manual/en/
> provides for PHP.
>
> To continue with our example, picture a page listing
> eq, eqv, and = that explains /with examples/ when to
> use each.  This would be for a single dialect (PLT
> Scheme) and a single language level--the one that
> working coders would want to use the large majority of
> the time (Pretty Big, is my guess).  Knowledge search
> and acquistion are a huge part of programming.  Making
> this simple, quick, and painless is vital to
> successfully competing with other languages for
> hearts, minds, and utilization.  With its many
> intrinsic advantages off-limits to procedural
> languages, Scheme can win. Most programmers are
> suckers for elegance.
>
> Another example of how PHP has become successful by
> keeping it simple: PHP allows dynamically changing
> language settings to allow inclusion of code written
> for a different configuration.  Can Scheme, similarly,
> unify dialects? e.g.,
> (setenv chicken1.3 (include a-chicken-script.scm)
> ) Just a thought from a novice.
>
> George H.
> _________________________________________________
>   For list-related administrative tasks:
>   http://list.cs.brown.edu/mailman/listinfo/plt-scheme