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=20
> the learning curve. =20
>=20
> People who are new to both emacs and Common Lisp
> aren't in the most enviable of positions as it is: for them=20
> there is great value in being able to find keybindings by=20
> searching the documentation for such. ;)
>=20
> Also, during the early learning stages a list of keybindings=20
> is a good learning tool as it is pretty much equivalent to=20
> "frequently used commands".
>=20
> I've used emacs for a few years, but "C-h m" isn't something=20
> I yet do by reflex. I probably should, but I'm only bringing=20
> this up to illustrate that overcoming emacs-cluelessness is a=20
> long-term project for at least some of it's users.
>=20
> That said, I can most certainly understand you reluctance to=20
> maintain multiple sets of documentation...
>=20
> Hence I'd suggest mentioning the "C-h m" &co under=20
> "Keybindings" in the Ilisp documentation. Or maybe a "Short=20
> 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.=20

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