Re: Poll: personal convenience vs. global improvement of docs
Gary Johnson <garyjohn@xxxxxxxxxxxxxxx> wrote:
> 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.
First of all, it's a pleasant surprise to learn that mutt is
attracting new users. How did we know this? I was under the impression
that newbies went for gui-based programs. Have I missed a similar poll
of newbies done to discover what specific difficulties they've faced?
Just what is driving this review? That said, anyone interested enough to
try mutt should be willing to read and understand the documentation.
What Gary says here should not be overlooked. Variable names in of
themselves mean nothing if they are not properly documented and
understood.
The trouble with this poll is not the little question of inconvenience
(there is none to me as I can easily make the switch), rather it seeks
my concurrence to ruin a vast corpus of currently accurate information
not so as to add new functionality to mutt but merely in the *hope* that
new information will prove less intimidating to new users. I do not think
that this hope is a sufficiently good reason to make the proposed
changes. In any case, I have seen many users for whom any problem
with fetchmail, postfix, procmail and so on is a mutt problem; it
bears repeating that a survey of new users and or experienced ones about
what best would make mutt easier to understand and use needed to
precede this poll.
FWIW, my vote is for simply categorising all the current variable
names in the sample muttrc. Group related items under descriptive
section names such as 'Getting Mail', 'Sending Mail', 'Reading Mail',
'Customising the look', 'Shortcuts' and the like. If the aim is
to aid new users, then they should be encouraged to start with the
sample config. Once you know that they are going by it, helping them
becomes a relatively simple matter.
Whatever is finally decided, and I hope the decision is made based on
a consensus arrived at after these discussions rather than the raw poll
results, the re-organised sample muttrc should also be put up in the
Wiki with the variable and function names linked to all the very
useful help already there.
s h e h u