[slime-devel] [Re: SLIME manual fixes]

[Jeffrey Cunningham]

On Sun Jan 21, 2007 at 09:07:04PM -0800, Bill Clementson wrote:
<snip stuff>
> 
> 1. Almost nobody reads long command lists
> 2. Unless they are automatically generated, they tend to get
> out-of-date fairly quickly
> 3. Contextual listings of the commands (such as are in section 3.2 for
> example) are much more useful. If someone is reading a specific
> section of the manual (for example, section 3.2.1.5 - Cross Reference
> Commands) because they want to learn how to do something, they will
> see that subset of commands that relates to the area that they are
> interested in. This is usually more relevant and there is more
> retention of the material since it is presented in a context where it
> can be best utilized.
> 4. Long command lists tend to add quantity rather than quality to
> documentation.
> 5. Most long-time slime users will probably rely on built-in emacs
> help commands (e.g. - C-h commands or find-function commands and
> source code) when they want to learn about a function. Therefore,
> command documentation in the manual should be targeted towards newbies
> who want to quickly learn functionality and towards experienced users
> who want to know more than function help and source might tell them.
> Long command lists serve neither newbies nor experienced users.

Interesting comments. 

I'm definitely one of the users that falls somewhere in between a
long-time user and a total noob, and I've actually grown rather
attached to the keybinding index. For example, I accidentally press
the wrong key combination and it does something I don't expect and I
want to find out what it was. I would usually have no idea what
section to look in. But can I look it up in the key-binding index. And
often, I'm not sure about a keybinding and find that its a lot less
work to visually browse the two pages and see it than drill down
through the various levels to find its section. Two pages doesn't seem
like a terrible burden. And the links to the sections get me in the
vicinity of similar commands very quickly. I guess the more I think
about it, the less I see it as a quantity vs quality issue.

Keeping the documentation up to date is always going to be a chore. I
wrote a script early on to extract the key-bindings and it was
partially successful. But there are many exceptions which made the
list incomplete. I don't know what can be done about that. I think
keeping those two indices up to date is far less trouble than
documenting all the undocumented functions I found. 

Incidentally, I pruned everything that wasn't "public" so far as I
could tell - meaning that I couldn't call it from either a key-binding
or a M-x command, I figured it probably didn't belong in the
documentation.

It seems like we lose nothing by by having the indices, and gain some
degree of lookup capability when it is needed. The bits are pretty
much free. 

My two cents. 

--Jeff