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

[Bill Clementson]

On 1/28/07, Madhu <enometh at meer.net> wrote:
> * "Bill Clementson"  <8757cb490701281120p7d88eb8eg5f6e6a01821d4061 at XXX> :
> [snip good points]
>
> | I originally opposed including both Appendix A (key binding index)
> | and Appendix B (function index) in the documentation for the reasons
> | I listed in my earlier post
>
> I read those reasons, but maintain that any decent manual should
> contain indices, and in the case of an emacs package, case keybindings
> are highly relevant. I supplied my own 2 reasons, that the manual
> should be correct documentation, and independent of a live emacs
> session, which may not be at hand. [Also see below about `KEY INDEX']
>
> When a live emacs session is available one could use the facilies of
> course to get the exact current state of things.

I really liked the original slime documentation (written, I believe,
by Luke Gorrie). It was concise, covered what I needed to know and was
fun to read. So far, the documentation hasn't deviated much from this
(I like most of the changes that Jeffrey has made and it's great that
someone has taken on the task of tidying up the docs).

However, I disagree with your assertion that "any decent manual should
contain indices" and also the implication that the manual (as it
currently is) does not represent "correct documentation". A manual
should be designed for an audience and I think the slime manual DOES
meet the needs of slime developers without function and key binding
indices.

> | Jeffrey has agreed and removed Appendix B. Since a number of people
> | have indicated that they think Appendix A (key binding index) is a
> | good idea, it might be worthwhile to keep it (although I still think
> | i is not useful).
>
> That may be presumptious and ignores how other people may have
> traditionally used good manuals.

I don't know that there is any good use case for keeping them. The key
bindings and functions are covered in context in other parts of the
manual. There's no need to duplicate that coverage in appendices.

> | However, if it is retained, it should be corrected to reflect the
> | different types of slime buffers and the key bindings that are in
> | effect in each. This will have the (in my mind) negative effect of
> | increasing the size of this appendix, making it more difficult to
> | maintain, and reducing its value to newbies.
>
> No, if you note the other manuals, the `KEY INDEX' cross references
> commands already listed in the manual.  Perhaps This would be
> sufficient in SLIME's case too.

My point was that not all key bindings are "in scope" in all buffers
in slime. If there is a key binding index, it should indicate
where/when a particular binding is in effect. Otherwise, a user looks
in the appendix, finds a key binding, tries it out, and gets a "key is
undefined" error.

> | However, if it is to be retained, it should at least be accurate.
>
> There is no disputing that the keybindings should be accurate, and if
> there is a disparity, it indicates a bug that should be addressed. The
> bug could be equally well in the code, (which may need to be fixed to
> conform to the manual) OR in the manual which would need to be fixed
> to conform to the code. Docs have this `good' stabilizing effect.

Code is written. Bugs are found. Code is fixed. Very rarely does
something that is written about key bindings in a manual contribute to
finding/fixing a bug. However, it is very easy for lists of key
bindings and lists of functions to get out-of-sync with the code. If
there is some alternative way of getting this type of key/function
documentation (and there is), then it is preferable to not have it
manually maintained as it will constantly need updating.

> There is no disputing that the keybindings should be accurate. I think
> one of the final nails in ILISP's coffin may have been the
> documentation of keybindings. (under this scenario: people downloaded
> it, read the documentation and then tried it).

I don't remember that the documentation of key bindings played any
part in the demise of ILISP. ILISP had become a bit bloated, harder to
hack, and tended to lock up too frequently with some CL
implementations.

--
Bill Clementson