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