From: Tim X <timx@nospam.dev.null>
To: help-gnu-emacs@gnu.org
Subject: Re: Failing to see the allure of Emacs
Date: Thu, 25 Mar 2010 19:42:53 +1100 [thread overview]
Message-ID: <87mxxweqr6.fsf@rapttech.com.au> (raw)
In-Reply-To: 9uudnY0F7J_qFjfWnZ2dnUVZ8oCdnZ2d@posted.visi
"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
next prev parent reply other threads:[~2010-03-25 8:42 UTC|newest]
Thread overview: 55+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-03-21 19:02 Failing to see the allure of Emacs Daniel
2010-03-21 20:22 ` David Kastrup
2010-03-21 20:47 ` Pascal J. Bourguignon
2010-03-21 21:00 ` akaiser
2010-03-21 21:26 ` Daniel
2010-03-21 22:16 ` Pascal J. Bourguignon
2010-03-22 4:05 ` Uday S Reddy
2010-03-21 22:21 ` David Kastrup
2010-03-23 17:22 ` akaiser
2010-03-23 17:52 ` Jeff Clough
2010-03-23 19:10 ` akaiser
2010-03-23 19:32 ` Uday S Reddy
2010-03-23 23:00 ` David Kastrup
2010-03-24 21:40 ` Tim X
2010-03-24 22:00 ` akaiser
2010-03-25 0:28 ` Jason Rumney
2010-03-25 1:03 ` Jay Belanger
2010-03-25 1:27 ` despen
2010-03-25 8:42 ` Tim X [this message]
2010-03-25 9:19 ` akaiser
2010-03-25 10:01 ` David Kastrup
2010-03-25 10:09 ` akaiser
2010-03-27 20:59 ` Giorgos Keramidas
2010-04-07 5:36 ` David Kastrup
2010-03-25 9:41 ` akaiser
2010-03-25 12:17 ` Tim Landscheidt
2010-03-25 12:24 ` akaiser
2010-05-04 19:03 ` Lennart Borgman
[not found] ` <mailman.28.1272999835.29092.help-gnu-emacs@gnu.org>
2010-05-05 7:15 ` David Kastrup
2010-05-05 20:40 ` Stefan Monnier
2010-03-25 12:45 ` Jay Belanger
2010-03-25 18:31 ` Uday S Reddy
2010-03-25 14:07 ` Ted Zlatanov
2010-03-25 14:49 ` David Kastrup
2010-03-26 4:14 ` Galen Boyer
2010-05-05 17:27 ` Joel J. Adamson
2010-03-21 21:02 ` Jeff Clough
2010-03-21 22:09 ` Pascal J. Bourguignon
2010-03-21 22:35 ` B. T. Raven
2010-03-21 22:45 ` Pascal J. Bourguignon
2010-03-22 0:21 ` Jeff Clough
2010-03-22 4:45 ` B. T. Raven
2010-05-22 2:38 ` Joseph Brenner
2010-03-21 22:58 ` John Bokma
2010-04-20 13:04 ` Jim Diamond
2010-04-20 17:15 ` Andreas Politz
2010-04-20 17:34 ` Jeff Clough
2010-04-21 14:26 ` Jim Diamond
2010-04-20 17:36 ` Glenn Morris
2010-04-21 14:31 ` Jim Diamond
2010-04-21 18:23 ` Stefan Monnier
2010-04-22 15:27 ` Uday S Reddy
2010-04-20 22:37 ` Tim X
2010-03-21 22:41 ` despen
2010-03-22 11:59 ` Stefan Kamphausen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87mxxweqr6.fsf@rapttech.com.au \
--to=timx@nospam.dev.null \
--cc=help-gnu-emacs@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.