<<< Date Index >>>     <<< Thread Index >>>

Re: Poll: personal convenience vs. global improvement of docs



On 2006-05-24, Rado S <rado@xxxxxxxxxxxxxxxxxxx> wrote:
> Moin moin fellows,
> 
> we need your vote to learn whether _you_ (personally, individually)
> are willing to accept
>       a major (single) change of your personal muttrc
> in favour of improved docs support for newbies by introducing
>       a muttrc variables naming scheme.

> I've collected a list of categories to be used as prefixes
> together with some name changes for more intuitive use.
> You can review and _edit_(!) the list for better suggestions:
> 
>         http://WIKI.mutt.org/?ManualVarNames

> /Discussion
> carries all so far accumulated contra naming scheme reasons and
> counter- arguments, which either completely negate or mostly
> invalidate them. It's up to you to decide how much this is true.
> This has been gathered from discussions about the issue with
> several different people.
> Please add more pro or contra to that page as you see fit or state
> it here on the mailing list or by private eMail. I'll add it then.
> 
> The main contra reason is that it would break the muttrc of all
> current users, and this would be too much a cost to pay.
> I don't ask you to ignore the current user base.

I was going to add some comments to the

    http://wiki.mutt.org/?ManualVarNames/Discussion

page, but that just doesn't seem like a very good medium for 
_discussion_.  My statement against the proposal on the Vote page 
is:

Gary Johnson: Reorganizing the manual and categorizing variables is
       a great idea, but once you do that, it doesn't matter what 
       the names are. If the documentation is poor, good names won't
       help newbies much. If the documentation is good, the names 
       won't matter to newbies. Users who follow mutt developments 
       could change from old to new names without too much hassle, 
       but everyone else, e.g., the ordinary user, would be confused 
       and ticked off by having to make a bunch of changes to 
       well-established and long-forgotten configurations with no 
       benefit to them.

To elaborate a bit on that, think of all the bizarre command names 
we've all had to learn to use various programs and operating 
systems.  The ones we don't use very often we look up when they're 
needed.  The ones we use often we just learn.

When it comes to writing the configuration file for any program, you 
pretty much have to sit down with the manual, figure out how 
preferences are set, and use whatever names and syntax the program's 
designer chose.  In the context of reading the manual, the names for 
settings don't matter.  While you are configuring the program, you 
remember whatever names were used for the settings.  Once you get 
the configuration the way you like it, you forget about the 
configuration file and forget the names.

Some programs, such as tin, create an initial configuration file 
that has a short sentence or so above each configuration variable 
explaining what it does.  Again, with the explanation right there, 
the name doesn't matter.

With good, searchable and/or indexed documentation, the user can 
search for the variable name and find its meaning or search for a 
word related to the thing being configured.  With a good table of 
contents, the user can easily find the topic covering the thing he 
wishes to configure.

The only time I have found the name of a variable or function to be 
important is when the documentation is so horribly poor or 
nonexistent that I have to guess what something does from its name.

In short, the benefit of changing names is minimal.

Changing the names used by such a well-established program as mutt 
means much more than just changing the code, the documentation, and 
users' configuration files.  One of the benefits of the open source 
or free software development and support model is that a lot of 
useful information is maintained on numerous users' web pages and in 
the archives of Usenet newsgroups and other discussion forums.  
Changing the names of mutt variables and functions is going to 
obsolete a lot of that information.  Some web pages will be 
rewritten, taking a lot of unnecessary time.  Other web pages that 
are not being maintained and the discussion groups will become 
useless.

The cost in time and lost information to the mutt community would be 
huge.

Making mutt easier for newbies to use and to understand is a great 
idea, but changing variable and function names is not the way to do 
it.  If you really want to help new users, add a section to the 
manual where variables are grouped functionally along the lines of 
your ideas for renaming them, and improve the rest of the manual by 
making the explanations more clear and with better cross-references.

Regards,
Gary

-- 
Gary Johnson                               | Agilent Technologies
garyjohn@xxxxxxxxxxxxxxx                   | Wireless Division
http://www.spocom.com/users/gjohnson/mutt/ | Spokane, Washington, USA