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

[Bill Clementson]

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