Re: Failing to see the allure of Emacs

[Tim X <timx@nospam.dev.null>]

"akaiser@visi.com" <akaiser@visi.com> writes:

> I understand all the objections made to my saying that the emacs documentation
> is incomplete, not up to date, and not readily usable, and I don't feel like
> arguing the matter merely in technical detail.  Some disagree.  That's cool.
> I wish them well.
>
> I have a relative who, before email, never wrote me.  Once she had email, she
> became a very lively correspondent.  Paper wasn't her medium, but email was.
>
> Got the idea?
>
> I can read source code and I do; but there's a lot of source code, and most of
> it is unrewarding reading.  I can use info, but I don't like it.  Please don't
> tell me "use info", because info is designed and intended not for reading, but
> for brief, casual online reference, and that is its cognitive organization.
> It's poor as a learning tool, at least for text-based and example-based
> learners like me.  I'm a fast reader and I like hectares of well-indexed text
> with lots of bookmarks: that's my best medium.
>
> If documentation is worth doing -- and I think it is -- then it's worth doing
> well, in a way that meets the needs of the people who'll actually use it.  In
> that light, emacs documentation seems to me to hold up not too well.
>
> Look through this newsgroup for all the places a response has said "Have you
> tried function such-and-such", or "that behavior is controlled by variable X
> except that the default is variable Y".  If the documentation were better,
> much of that would disappear.
>
> When a literate, conscientious user with decades of programming experience,
> decades of experience writing documentation, decades of using emacs, and
> decades of support for free software says something like what I say, trying to
> argue him down is unproductive.  Of course I appreciate all the concrete help
> I've gotten here and in other such forums, but it sure would be good to have
> complete, up to date, readily usable documentation.  (Smiling.)
>

Your statements are noted and on some levels your criticisms have some
validity. However, the responses you recieved are largely due to the way
you initially expressed the issue. Rather than saying that the existing
format of the documentation is not one you find condusive to your
specific style of learning or use, your statement was that emacs lacked
documentation. These are two different things. 

Emacs has very comprehensive documentation. There is a reason it is
often referred to as the self documenting editor. Most of the standard
functions and variables have documentation that is easy to lookup. Emacs
has a whole range of facilities to make it easy to find documentation on
these things. Many may not appear intuitive to anyone unfamiliar with
emacs and some people even take some time to become familiar with these
facilities, but this is a different issue to documentation not existing.

I would also suggest that your perspective on info would be worth
re-examining. The three main info manuals that come with emacs all have
extensive indexing, cross-references, bookmarks, etc. Due to the fact it
was one of the very first hypertext type manual systems, it can appear
very alien at first, but once you become accustomed to it, it is both
useful for quick reference and lookup as well as general learning of
concepts, techniques etc. Based on your style of learning, I would
highly recommend the emacs lisp intro as a good starting point. This
will give you the higher level explinations and instruction/example
approach you prefer. The emacs manual is then sful for specific areas
and the emacs lisp reference provides all the nitty gritty details you
will need to write emacs lisp or get more specific details. 

Of course, the final point to mention is that emacs is an open source
project and its documentation is only ever as good as what users are
prepared to contribute. Based on your years of experience and your
percieved weaknesses in what exists, perhaps trying to
add/improve/extend what is there would be a more profitable use of time
than complaining that what is there is no good because it doesn't suit
your (and possibly others) way of learning. It is easy to criticise, but
more rewarding to improve. If you see a weakness, do something about it.
As soon as you show your actually more interested in improving the
situation rather than just moaning about it, I expect a number of people
will be keen to help. 

Tim


-- 
tcross (at) rapttech dot com dot au