RE: RE: [Ilisp-devel] Re: Using Emacs as a Lisp IDE

From: Nikodemus Siivola on Tuesday, July 15, 2003 8:57 AM
> IMHO, the main value for keybinding documentation is easing 
> the learning curve.  
> 
> People who are new to both emacs and Common Lisp
> aren't in the most enviable of positions as it is: for them 
> there is great value in being able to find keybindings by 
> searching the documentation for such. ;)
> 
> Also, during the early learning stages a list of keybindings 
> is a good learning tool as it is pretty much equivalent to 
> "frequently used commands".
> 
> I've used emacs for a few years, but "C-h m" isn't something 
> I yet do by reflex. I probably should, but I'm only bringing 
> this up to illustrate that overcoming emacs-cluelessness is a 
> long-term project for at least some of it's users.
> 
> That said, I can most certainly understand you reluctance to 
> maintain multiple sets of documentation...
> 
> Hence I'd suggest mentioning the "C-h m" &co under 
> "Keybindings" in the Ilisp documentation. Or maybe a "Short 
> Guide to Developing with Ilisp" would be the correct solution.

Ummm, I already put the following at the bottom of the intro to the
"Keybindings" section:

"Remember that you can type `C-h m' at any time to see help on the
current major mode, which will show (among other things) a list of all
currently active keybindings."

:-(

I agree that a "Short Guide to Developing with Ilisp" would be a useful
thing. That will (hopefully) be what my ILC2003 paper on "Using Emacs as
a Lisp IDE" will turn out to be. However, it will cover both Ilisp, eli
& inferior lisp modes, so may not be as succinct as an ilisp-only guide
would be. My intention was to post a version of the paper on the CL
Cookbook site in order to make it more generally available for anyone
who wants to use Emacs to develop lisp code. 

This brings up the generic question of how much documentation is
"enough" and what is the best way to provide supplemental documentation?
I think it is difficult to know exactly where to draw the line between
package-specific documentation (that needs to be included with something
like ilisp) and tutorial-type documentation. My own feeling is that the
former needs to be concise and just enough to get users going (because
after people become comfortable with a package, most rarely return to
the documentation) and that is what is included with ilisp at the moment
(although I'm sure there's lots of room for improvements). The latter
(tutorial-type documenation) is more appropriate for a site like CL
Cookbook which can provide a better range of tutorial topics and can be
maintained by a larger population. I think Edi Weitz deserves a lot of
praise for setting up the CL Cookbook site as it gives the community a
place to collect tutorial-type documentation.

If you like, I can send you an early draft (once I have something to a
reasonable state) and you can provide me with feedback as to whether it
might be an adequate alternative to a "Short Guide to Developing with
Ilisp" and whether the combination of the ilisp documentation and the CL
Cookbook would provide beginners with sufficient "getting started"
material.

I appreciate your comments and feedback.

--
Bill Clementson



-------------------------------------------------------
This SF.Net email sponsored by: Parasoft
Error proof Web apps, automate testing & more.
Download & eval WebKing and get a free book.
www.parasoft.com/bulletproofapps1