Hi Jeffrey,
On Sun Jan 21, 2007 at 02:32:32PM +0100, Luke Gorrie wrote:
The manual improvements look good, great work!
Appendix A (index of keybindings) is excellent but I'm not sure that Appendix B (index of functions) is worth its price in virtual trees. Are there good "use cases" for it?
My reasoning was that if you want to find out what a function does without doing a text search it may be your only option. It isn't always clear what section you would find it in from the name alone.
But what really induced me to add it was when an upgrade of xpdf at work broke its text search capability and all I had on that machine was slime.pdf. ;-)
If no one else thinks it could be useful, I'll take it out.
I'd like to second Luke's praise for your efforts in improving the SLIME documentation.
However, with regards to the 2 appendices, I am opposed to long lists of commands such as are in Appendix A and Appendix B because I think (for the most part) they are not of value. My reasons are:
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.
In general, I feel that occam's razor should apply to documentation. Usually, "less is more" with good technical documentation.
However, one thing was highlighted for me in the texi file for Appendix B (which has the list of ALL slime commands). The commands that aren't documented in the manual are commented out in the texi file so that they won't appear in the generated documentation and there are a lot of undocumented commands. I hadn't realized how many undocumented commands there were. Some of the commands are "internal" and shouldn't be documented in the manual; however, others are worth adding to the manual.
So, my opinion would be that the two appendices should be removed. It would be nice to have some of the undocumented commands added to the manual as well as more "how to" information of the type found in the Tips & Tricks section of the manual.
Anyhow, just my 2 cents.
-- Bill Clementson