about coders, docs and users
=- cga2000 wrote on Thu 17.Aug'06 at 16:01:06 -0400 -=
> I can't think of a better wording but what would have helped me
> tremendously -- and still would.. is a "User Guide".
Be patient and hopeful that some (mutt-dev) decisions indicate
appreciation of improving docs to make me work on this or that
somebody else picks it up in the meantime.
But until then, Patrick Shanahan wrote useful advice.
=- Patrick Shanahan wrote on Thu 17.Aug'06 at 16:16:49 -0400 -=
> * cga2000 <cga2000@xxxxxxxxxxxxx> [08-17-06 16:03]:
> >
> > I can't think of a better wording but what would have helped
> > me tremendously -- and still would.. is a "User Guide".
>
> With the documentation that mutt has, probably one of the best
> in linux, the best 'User Guide' is experimentation.
Hard to judge, but for sure there is a lot of worse as well as
some better. However, even the best things don't have to stop
improving if there is potential to go.
> After all, with a good manual to start and text configuration,
> if you have a question, try different things to see what works.
Not all people learn the same way. Some need more "guidance" than
others. Do we want to drop/ lose/ scare away all those who haven't
the qualities required from the start to be successful with the
current state of docs and this "learning by trying" approach?
(which btw costs a lot of time, too, which not everybody is willing
to _waste_, ... errr, spend on getting a few simple things to work,
that most probably many others have and still will run into)
> When you find something that you think should be known, add it
> to thw wiki.
Even though this is a good idea, this is actually the biggest problem:
- those needing help can't write the guide (yet).
- those knowing the answers don't know how to write it usefully.
- neither wants to spend the time _on this_ for others.
(sacrifices for user-friendliness for others are rare)
So once beginners and pros should get together to work on it, or hope
that some pros feel itchy enough about it to do it on their own.
> Else, having plenty of time on you hands, generate a basic
> 'Users Guide' and ask for contributions to your project. Mutt
> *is* open source.
UserStory has links to some external attempts. Ideally I wanted to
compile all this into the MuttGuide...
Maybe you can add your ideas, desires, wishes about a useful
guide to UserGuide (linked from MuttGuide).
> *Many* questions as posed here that could be answered with very
> simple experimentation. A few simple hints, begin with a blank or
> very basic rc-file, send mails locally to yourself or root or some
> alias that you have set, capture the output, examine your failures
> and successes and ask yourself why one worked and another failed.
DebugConfig has more (specific) advice for this.
=- Alan Mackenzie wrote on Thu 17.Aug'06 at 22:08:01 +0100 -=
> > Good docs are generally underappreciated to work on.
> > [ about coders and docs ]
>
> I am a developer, and I've spent ~200 hours knocking "my" manual
> into shape.
There are always exceptions like you (and me and others), only
that we're in the minority with our understanding of its importance.
=- cga2000 wrote on Thu 17.Aug'06 at 16:38:18 -0400 -=
> > Good docs are generally underappreciated to work on.
> > [ about coders and docs ]
>
> not necessarily .. the returns in terms of customer satisfaction
> and a marked decrease of the volume of pointless calls to tech
> support can be quite significant.
> .. not sure how this transposes to the gnu/linux world, though.
Tada, you nailed it. At least as far as I could tell such
considerations haven't been a big part of mutt-dev yet.
Or rather: it's not measured by what can be achieved with docs but
rather code functionality only. As I said (for mutt): docs are
underappreciated to be considered seriously/ equally with code.
As long as it works fine for those who use mutt _now_, there is
nothing to worry for mutt-dev.
Primary goal is to make it _work_ well for those who know how it
works, not to learn/ use it well. This "learn/ use" stuff is left
for everybody himself and relying on 3rd party people to cover
what mutt-dev doesn't like itself to do/ care for.
> Not entirely. When problems surface there are cases where
> problems are easier to address when you are dealing with an
> informed user base.
Generally true, but not for mutt-dev, since it's not mutt-dev who
has to deal with them, but mutt-users, so they don't have to waste
_their_ time with this uninformed user base.
If they _had_ to answer _all_ themselves, they'd appreciate it a
lot more. But luckily for them, there are enough 3rd party people
around willing to jump in to make up for what the docs lack in the
1st place. :-/
> > Plus, it takes _a lot_ more time to improve whole docs than
> > a small piece of code.
>
> That's why GUI's usually come without those fat manuals .. Since
> everything is perfectly intuitive, it's totally unnecessary ..
> Time is money.
> {...}
> A bit like trying to learn a foreign language by reading its
> dictionary from cover to cover..?
*sigh*
I know, but mutt-dev doesn't yet, or rather doesn't care.
After all you get the code for free and you _still_ demand more? ;)
=- cricketc@xxxxxxxxx wrote on Thu 17.Aug'06 at 21:24:50 -0500 -=
> Just want to say thanks for working on the documentation. I do
> appreciate having things spelled out in the manual so I don't
> have to do as much testing myself.
Maybe if we accumulated a _voiced_ critical mass something could
change.
--
© Rado S. -- You must provide YOUR effort for your goal!
Even if it seems insignificant, in fact EVERY effort counts
for a shared task, at least to show your deserving attitude.