Re: Emacs setup assistants

[David Kastrup]

Eli Zaretskii <address@hidden> writes:

> > From: David Kastrup <address@hidden>
> > Date: 20 May 2004 12:57:11 +0200
> > 
> > > A tool such as the one being discussed needs mostly small chinks
> > > of plain text interspersed with hyperlinks, something for which
> > > Customize (and indeed even Help functions) already have the
> > > necessary infrastructure, or at least large parts of it.
> > 
> > Small? No.  An assistant has to _explain_ things, and the ways in
> > which they are related.
> 
> In my experience, long explanations are never read.

I am not talking about long explanations.  I am talking about about
step-by-step explanations of how to customize what for what
functionality.  Take, for example, the preview-latex manual (should be
online at <URL:http://preview-latex.sourceforge.net/manual>. It
contains a section about easy customizations
<URL:http://preview-latex.sourceforge.net/manual/Simple-customization.html#Simple%20customization>
and it contains a section about more advanced topics
<URL:http://preview-latex.sourceforge.net/manual/The-Emacs-interface.html#The%20Emacs%20interface>,
explaining the basic operation of the package and all related
variables you might consider for influencing the stuff.

People tell us that this manual is reasonably good, and that they
read it.  It is hard work to keep it at a consistent high quality.
If we could replace things like
"To do this, press M-x customize-variable RET
preview-default-option-list RET and make sure that [...]" with
"press here to customize this behavior", then people would not be
forced to jump between customization buffers and manual forth and
back.  Exactly because long explanations are not often read, it is
important that we have a few buttons to actually try out, with
hopefully immediate feedback in a separate window.

> > Isolated customization strings don't do that.
> 
> I didn't say isolated strings.

You said, this is nothing that could not be done with variable
documentation/customize documentation.  This stuff is
variable-specific.  You have no idea in what sequence the user might
try customizing variables.  Therefore, you are working with isolated
strings.  They are not arranged by topic, but by variables.

That's isolated, without context.

> Writing a 10-sentence explanation for a specific aspect of something
> doesn't require something as elaborate as Texinfo.

And where do you put this explanation?  How does the user get the
idea to access it in the first place?

> > You don't get a coherent explanation and layout of what to do in
> > what order and what influences what.  You get a twisty little maze
> > of crosslinks with pieces of information scattered around, and the
> > coherent ideas of the design having no place to be sitting.
> 
> The, IMHO, challenge is to organize those pieces of information in a
> way that in every specific case we only display the text that
> explains what the user currently cares about.

But the name of a variable is the worst user interface for a user to
tell the system what he cares about being informed: if he knows the
name of the variable, he already _has_ the information and does not
need an assistant.

> For example, when I need to set up a port for some service, I don't
> want to hear a lecture about TCP/IP and ports in general, just clear
> and practical suggestions for coming up with the port number for
> that specific service.

And so we hide that information in the documentation string of some
variable the user can't have a chance of guessing?

No, if you are looking for information about how to achieve a certain
functionality, you use the concept _index_ of an appropriate document.
Like the package's Texinfo manual.  _Then_ you get to know which
variables to customize just how.  And if you can do the customization
right in the buffer where you looked them up, so much the better.

And we can write special manuals, assistant documents, that are
explicitly designed to provide a short step-by-step procedure for
getting an overview and getting it configured.

Customization strings are not something organized as a step-by-step
recipe.

Such documents save you reading long-winded explanations and trying to
understand them and devise an action for working on them: instead you
click the proposed buttons.

> > That's not what an assistant is supposed to do: an assistant is
> > concerned with setting up a package, not with customizing a single
> > variable once you have found out that you might want to customize
> > _that_ variable.
> 
> Again, the challenge IMHO is to break a complex issue into a
> sequence of well-defined short help messages, and a framework that
> guides the user thru that sequence.

Where should those help messages come from?  Where do you get a
sequence, a coherent layout, an order?

> No one will ever read a 10-page explanation just to set up a package
> (well, perhaps except you and me).

Who is talking about a 10-page explanation?  Again, the preview-latex
manual has a section "Easy Customization" and it has a section "The
Emacs Interface" or such, and the latter has a density of perhaps 6 or
7 lines of text per referenced variable.  That's not a 10-page
explanation, and every variable is entered in the variable index of
the manual.

Basically you say "Ok, our current documentation tends to be so bad
that nobody reads it, because it requires work understanding and
using it.  So let's not try to make it easier to use, and let's not
make it easy for anybody else to write better documentation."

I repeat: people _do_ read our manual, and it is not easy to get a
quality that is consistently high.  Adding some ways to make it both
easier to use and to write good manual sections (or special-purpose
assistant nodes or files) is not a mistake.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum