Problems of Emacs Manual

The emacs documentation is quite outdated. It is written with 1980's mindset, with some one thousand pages in a verbose way. Perhaps half of bulk are not necessary and can be edited out as improvement.

Although its technical writing is impeccable and one of the best in tech industry, but because it's written in the 1980's or early 1990 computer era context, few people reads it today, except a few hardcore emacs fans.

The document is written is a verbose manner. For example, it starts with tens of pages to explain the concept of screen, User input, keys, Help system, copy and pasting etc. Although it is complete… but many of these concepts are rather quaint and irrelevant. When emacs was in 1980s, it was one of the very few comprehensive system, one of the first large application, with concepts that doesn't exist anywhere. It is, in fact, THE system where people can learn and spread the ideas to other applications.

But today, after 20 years of evolution in the computing industry, with applications changing from military research to office appliances like word processors and spreadsheets, to web browsing, gaming, video watching, and its users changed from researchers to every household laymen, technologies in both software and hardware … Emacs is hardly the only system there is, in fact is rather a minor player among the multitudes of computing applications and systems, nor is it even the major text editor (think of web browsers, vast amount of diverse APIs and databases systems, Java, IDEs such as Visual Studio, Eclipse/JavaBeans, X-code…)

For vast majority of people, including programers, the primary drive to using a tool is to get the job done. They are not going to spend a day, week, or month to systematically acquaint themselves with the emacs system of lingoes and environment. They simply want to know how they can use emacs effectively to do whatever they wanted to do. Only gradually, they may be introduced to emacs's immense documentation, which is actually the road for most of us too.

So, emacs documentation can benefit from a major revamp, reducing its size to perhaps 50%, get rid of mentions of systems or lingoes that has been defunct for 1 or more decades, or rid of the hundreds of pages that discuss concepts in some monolithic way that every computer user knew already (such as copy, paste, screen, input…).

… for example, the manual's first paragraph starts thus:

Emacs is the extensible, customizable, self-documenting real-time display editor. This Info file describes how to edit with Emacs and some of how to customize it; it corresponds to GNU Emacs version 22.1.50.

This paragraph illustrates its mindset of the whole doc quite well. This paragraph is verbose and somewhat irrelevant to today's users. People needn't be told how extensible emacs is. When they use it, and if it is really great and extensible, the users will experience it and know. Just about all applications today, are all extensible in some way. They have APIs or plug-ins or modules, remote call procedures etc. The manual then mentions “customizable”. Again, this adds fat to the manual. Take the point of view that people in modern society are all very busy. They are not in a some idyllic hacker community of the 1980s at MIT. They simply come to emacs to use it, or lookup a manual when they didn't know how to do X. The manual should be direct and to the point, and can trim out meta-remarks of the 1980's mentality. The manual then mentions “self-documenting real-time display editor.”. To vast majority of professional programers today, they'll just go “huh?”. (professional programers here is defined as those who makes income by programing or sys admin. It includes and perhaps largely consists of, for example, HTML and PHP coders, which elite hackers who read newsgroups here often sneer at.)

(Note: The emacs phrase “real-time display editor” refers to the fact of typing something and immediately see it on screen, as opposed to the common way of text editing in the 1980s, so-called line editors, where user enters a command, execute it, then the display updates, even for simple things as inserting a word or deleting a character.)

The jargon “self-documenting” is rather meaningless. What it is meant in the 1980s, from today's point of view, is simply a software that is very well documented with a integrated and comprehensive help system. However, the fact is, compared to today's computing era, the integrated nature or comprehensiveness of emacs is in no way outstanding. Java, Perl, PHP, all have massive documentations, “integrated” online with web browsers, and all the associated modern technology of HTML/XML/CSS/javascript etc. In many respect, they are also integrated with online forums, and self-generating systems (such as javadoc) etc.

In the 1980s, emacs's help system, together with its texinfo technology that lies behind it, is unique, outstanding beyond its age. Today, it is just quaint.

Then, the manual uses the phrase “real-time display editor”. Again, something from the 1980s mindset. In the 1980s, the term “real-time display editor” is used to contrast to common method of text editing of that era, so-called Line editors, such as unix's “ed” and DOS's “edlin”, where user edit a text file by commands, in a command-then-display cycle. It's something very silly from today's point of view, like the notion of punch-cards.

Today, a text editor is just a text editor, not some “real-time display editor”. The use of that phrase in the manual has no concrete purpose, other than nostalgia for old emacs users.

Emacs's user base has been steadily declining, from maybe more than 50% of market share among programers in the 1980s, to today perhaps less than 1%. I think emacs will be here to stay, at least for the few of us hardcore geeks, but i think it can be made so that vast majority of other coders will find it also usable.

See also: The Modernization of Emacs, in which i give some detail about other changes i consider more important than the documentation revision discussed here.