Prev: Remembering information during compilation , part 2
Next: Checking for declarations in macros
From: Xah Lee on 30 Nov 2009 18:19
In the emacs manual, the first 3 sections are:

* Distrib:: How to get the latest Emacs distribution.
* Intro:: An introduction to Emacs concepts.
* Glossary:: Terms used in this manual.

This is typical opening style of manuals of the 1980s and 1990s.
Today, software do not come with manuals. The need for such manual
doesn't exist anymore since about 2000s, and are replaced by intuitive
user interface, interactive help, and also because increased computer
literacy.

The first 2 paragraphs of the intro section goes like this:

Introduction
************

You are reading about GNU Emacs, the GNU incarnation of the
advanced,
self-documenting, customizable, extensible editor Emacs. (The `G'
in
`GNU' is not silent.)

We call Emacs "advanced" because it can do much more than
simple
insertion and deletion of text. It can control subprocesses,
indent
programs automatically, show multiple files at once, and more.
Emacs
editing commands operate in terms of characters, words, lines,
sentences, paragraphs, and pages, as well as expressions and
comments
in various programming languages.

Note how silly it is. Among its explanation of “advanced” features, it
actually explicitly lists that its “advanced” features include: “more
than inserting/deleting text”, “ability to show multiple files”,
“indent programs automatically”, or comment handling. Ask your
programer colleagues, at Google, Microsoft, yahoo, ebay, amazon, ...,
if any of them consider these features “advanced”, or not in any of
today's programer editors, such as Microsoft Visual Studio, Notepad++,
Xcode, Textmate, Eclipse IDE.

The emacs manual is filled with these outdated verbiage. Perhaps as
much as 30% of it. When a 1/3 of manual is filled with useless info,
it is not a wonder few people actually read it.

Further readings:

• Problems of Emacs's Manual
http://xahlee.org/emacs/emacs_manual_problem.html

Xah
∑ http://xahlee.org/

☄
From: Tim Bradshaw on 2 Dec 2009 14:37
On 2009-11-30 23:19:24 +0000, Xah Lee <xahlee(a)gmail.com> said:

> The emacs manual is filled with these outdated verbiage. Perhaps as
> much as 30% of it. When a 1/3 of manual is filled with useless info,
> it is not a wonder few people actually read it.

Write an up-to-date one.

From: maximinus on 4 Dec 2009 01:04
On Dec 3, 3:37 am, Tim Bradshaw <t...(a)tfeb.org> wrote:
> On 2009-11-30 23:19:24 +0000, Xah Lee <xah...(a)gmail.com> said:
>
> > The emacs manual is filled with these outdated verbiage. Perhaps as
> > much as 30% of it. When a 1/3 of manual is filled with useless info,
> > it is not a wonder few people actually read it.
>
> Write an up-to-date one.

If Xah writes the manual we would get 30% verbiage converted into 50%
flame-bait and 50% garbage.
From: Paul Donnelly on 4 Dec 2009 12:55
maximinus <maximinus(a)gmail.com> writes:

> On Dec 3, 3:37 am, Tim Bradshaw <t...(a)tfeb.org> wrote:
>> On 2009-11-30 23:19:24 +0000, Xah Lee <xah...(a)gmail.com> said:
>>
>> > The emacs manual is filled with these outdated verbiage. Perhaps as
>> > much as 30% of it. When a 1/3 of manual is filled with useless info,
>> > it is not a wonder few people actually read it.
>>
>> Write an up-to-date one.
>
> If Xah writes the manual we would get 30% verbiage converted into 50%
> flame-bait and 50% garbage.

Yeah, but I've always wanted Emacs to swear back at me.
From: Tim Bradshaw on 4 Dec 2009 14:45
On 2009-12-04 06:04:51 +0000, maximinus <maximinus(a)gmail.com> said:

> If Xah writes the manual we would get 30% verbiage converted into 50%
> flame-bait and 50% garbage.

Perhaps we would, but I'd rather have that than the "it's no good, but
I'm not going to fix it" thing: that's just the sound of someone
wasting their time.

 | 
Pages: 1
Prev: Remembering information during compilation , part 2
Next: Checking for declarations in macros