A Dichotomy of Documentation

September 24, 2025

I have often grumbled about official documentation for open-source software. Perhaps I should not, but I did.

Hundreds of pages of specialized vocabulary, deployed without definition, can become a burden on the back rather than a tool in the hand.

A tone and writing style rooted in the Academical First-Person Plural, “We”, as in, “We do this-and-that,” and “We say such-and-such,” can make it sound written for those who already know the stuff, to the exclusion of us unworthies who do not.

But not always. One sometimes encounters documentation which feels more welcoming to a newcomer. My efforts to learn the LISP programming language provided in the Emacs editor brought me into contact with examples of both kinds recently.

Allow me to begin with gratitude to all the volunteers who generously create and maintain good open-source software such as Emacs and its LISP, with a special bow to those who write the documentation. I understand the difficulty of choosing how much to say.

I have struggled myself to find a good middle path between excessive clarity and befuddling brevity when I try to describe how software works.

Examples Tell the Tale

Both of the documentation examples relate to the Emacs editor. They are available online from the GNU Project, an open-source software consortium, at the following web address: https://www.gnu.org/software/emacs/documentation.html

The two documents discussed here are The Emacs Manual and Introduction to Emacs Lisp Programming.

I allow the sources to demonstrate their differences of tone and writing style, in their own words.

The following is taken from the Emacs Manual, Section 8.1, Inserting Text. Emacs is first and foremost a text editor — a pretty good one, in fact. You’ll get no complaint from me.

Here, eight chapters into the Manual, it finally gets around to saying that you can simply type any keyboard character you want. But then, perhaps from pride in the product, it hurries on to tell you much more.

You can insert an ordinary “graphic character” (e.g., ‘a’, ‘B’, ‘3’, and ‘=’) by typing the associated key. This adds the character to the buffer at point. Insertion moves point forward, so that point remains just after the inserted text. *Note Point::. To end a line and start a new one, type <RET> (‘newline’). (The <RET> key may be labeled <Return>, or <Enter>, or with a funny-looking left-pointing arrow on your keyboard, but we refer to it as <RET> in this manual.) This command inserts a newline character into the buffer, then indents (*note Indentation::) according to the major mode. If point is at the end of the line, the effect is to create a new blank line after it and indent the new line; if point is in the middle of a line, the line is split at that position. To turn off the auto-indentation, you can either disable Electric Indent mode (*note Indent Convenience::) or type ‘C-j’, which inserts just a newline, without any auto-indentation. As we explain later in this manual, you can change the way Emacs handles text insertion by turning on “minor modes”. For instance, the minor mode called Auto Fill mode splits lines automatically when they get too long (*note Filling::). The minor mode called Overwrite mode causes inserted characters to replace (overwrite) existing text, instead of shoving it to the right. *Note Minor Modes::.

Another Emacs-related manual takes a different approach. In the Emacs Lisp Programming Manual, documentation author Robert J. Chassell calls attention to the difference in this introduction on Page 2.

For Whom This Is Written

This text is written as an elementary introduction for people who are not programmers. If you are a programmer, you may not be satisfied with this primer. The reason is that you may have become expert at reading reference manuals and be put off by the way this text is organized.

An expert programmer who reviewed this text said to me:

I prefer to learn from reference manuals. I “dive into” each paragraph, and “come up for air” between paragraphs.

When I get to the end of a paragraph, I assume that subject is done, finished, that I know everything I need (with the possible exception of the case when the next paragraph starts talking about it in more detail). I expect that a well written reference manual will not have a lot of redundancy, and that it will have excellent pointers to the (one) place where the information I want is.

This Introduction is not written for this person!

Firstly, I try to say everything at least three times: first, to introduce it; second, to show it in context; and third, to show it in a different context, or to review it.

Secondly, I hardly ever put all the information about a subject in one place, much less in one paragraph. To my way of thinking, that imposes too heavy a burden on the reader. Instead I try to explain only what you need to know at the time. (Sometimes I include a little extra information so you won’t be surprised later when the additional information is formally introduced.)

Emacs software, the Lisp programming language built into it, and the two manuals mentioned above are published by the GNU Software Project. The Lisp programming language is provided also, in a different way, by another GNU software system called GUILE, an acronym denoting a Language for Extending other programs.

The manual for GUILE takes a dim view of murky documentation. When some part of the documentation is not clear and does not make sense to you even after re-reading the section, it is a bug. In other words, uninformative documentation is as much in need of attention and correction as any error in the software code.

Richard Stallman led the founding of the GNU Software Project and devoted his career to advocating for free software. He offers the following thoughts in an appendix of the Introduction to Emacs Lisp Programming.

The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals that we can include in these systems. Many of our most important programs do not come with full manuals. Documentation is an essential part of any software package; when an important free software package does not come with a free manual, that is a major gap. We have many such gaps today.

Stallman adds, ...writing good English is a rare skill among programmers..., which perhaps describes the problem succinctly.

Both code and the documentation of it are difficult to write well. For one thing, the process never ends. Robert Chassel says one more thing about this, with respect to code.

...some consider the most insidious type of bug (to be) the bug of omission. This is not the kind of bug you can find by studying the code, for it is not in the code; it is an omitted feature. Your best actions are to try your program early and often; and try to arrange, as much as you can, to write code that is easy to understand and easy to change. Try to be aware, whenever you can, that whatever you have written, will be rewritten, if not soon, eventually. A hard maxim to follow.

I would say the same, humbling insights apply to writing the documentation also. It is a bug when documentation omits something important, perhaps a thing so routinely familiar to experienced users that the writer assumes, everyone already knows or should know this, except not everyone does know it and newcomers cannot be expected to.

A friend of mine likened it to a Pilots’s Operating Handbook for a helicopter that details every mechanical and electrical system and how to operate the flight controls but... omits how to open the door from the outside.

After reading these documents during my recent study of Emacs and Lisp, I recognize that people leading these wonderful projects are well aware of their documentation challenges.

They depend to a large extent on volunteers donating their expertise. Sometimes the resources and the people simply get exhausted.

It tells me I should not find fault with the people. Moreover, free-software folks would not stand in the way of my offering my own work to fill any shortcomings I perceive in their work product.

Well-meaning users of the software may put articles online with a view to helping. For example, a short explanation of how to open the helicopter door. I am one of those people. Recently I posted two articles about the Lisp programming language in Emacs:

• Run an Emacs Lisp Script from the Command Line
• Let LISP Deal the Cards for Your Next Game of Bridge

Chances are, I shall soon notice many corrections to make and omissions to fill, both in my code and in the text of those two articles. What I said at the start, that I often grumble, targets my own work too.

As I have written elsewhere, even difficult documentation eventually repays study. One need not learn everything about a program before using it. Given that software changes over time, the work of learning about it never ends. Paraphrasing Chassel, the best actions of someone learning new software are to try working with it early and to continue working with it often.

For Emacs, a pretty good text editor, that means: Hey! just start typing! When you bump into the need to learn something, as surely you will do, go find it in the documentation. Strongly felt need to know is the best motivation for learning.

For Lisp, it means to write some trivial code; get it working. Then continue to work on it. Make it better. Then make it better yet. Writing and revising documentation, right along with the code, would aid learning both aspects of the craft.

My previous post to The Code Diary was on September 8th as I was just beginning to learn the Emacs editor. Between that time and this writing I wrote articles and Lisp-language programs to build familiarity. The fruits of that work appear on sibling website such as IowaDave.com and maybe a few others.

Onward!

I began September not knowing that I would spend it finding my way into Emacs and Lisp programming. Now I can say I learned something. And now, September is mostly spent. I feel ready to move on into something else. What shall it be? I do not know, and I do not need to know.