On Sun Jan 21, 2007 at 09:07:04PM -0800, Bill Clementson wrote: <snip stuff>
- Almost nobody reads long command lists
- 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