The Documentation Challenge

August 23, 2025

Describing code presents a Goldilocks problem: how much description is just right, neither too little nor too much?

This article is going to be a kind of meta-article, writing about writing-about-code, rather than writing about some actual code. I shall use Jekyll, a web-authoring software, for an example.

I looked into using Jekyll because it can automate the painstaking procedure of updating navigation links when adding a new article. Step one of learning any software is to install it for hands-on purposes. Step Two is to read all of the documentation. Whoa, there.

Or should I say, Woe Is There.

Jekyll is lovingly maintained by the core team of volunteers, states the footer on every page of Jekyll’s documentation. I believe it. They love maintaining it so much that they exhibit a kind of insiders-only way of talking about it.

In other words, I feel quite sure that folks who know and love Jekyll very well can get a lot of value from the documentation they publish about it. The stuff reads like reminders of prior-acquired knowledge. It uses specialized vocabulary before it defines the words. Little ol’ me, the new kid in school so to speak, struggles to comprehend.

In fairness to the documentation writers, this problem yields to study. A term used without explanation in one place may get explained somewhere else in the reference material. A reader gains familiarity with the terminology by repeated reading. A list of challenges facing the writers of documentation might well begin with simply organizing the vocabulary: define first, then use.

Comes here, however, an objection from experts. Complex code such as Jekyll usually depends upon (that is, actually incorporates) other code that may well be the work of another, different team of loving volunteers. The objection is that a dependency, as such helper-code is called, will have its own, specialized terminology. The words will properly be defined and explained in that software’s documentation.

A Jekyll expert might thus feel entitled to use words from that other documentation without bothering to repeat their definitions. Newcomers to Jekyll are expected to launch a scavenger hunt through all the different documentation sources for the supporting software on which Jekyll depends.

For example, the Jekyll documentation on a certain feature, called the highlight tag, appears to assume that the reader is Archaeologist enough to do such digging. Jekyll heavily depends upon another software systems, named Liquid. In turn, Liquid includes a dependency on something called Rouge. The novice is expected to delve down through the layers into the documentation for Rouge before finding answers about how Jekyll’s highlight feature works.

Let them learn it the same way we loving maintainers did, the expert seems to say.The struggle will do them some good.

This attitude of never-repeat-an-answer shows up in online community help web sites. Someone will pose a question, When I type the xyzzy command it gives an error: ‘frammis not found’. Please help me.

Too often, some self-styled expert will respond, This question has already been answered! RTFF!!! The abbreviation stands for something like Read The Full Forum. To reach for help is to be deemed unworthy of receiving it. It puts me off.

How might I reform my complaint as a constructive contribution to the challenge facing writers of documentation?

Much of my writing on the web aims to document something I learned about code. The challenge boils down to selecting the scope and style. The choice begins by deciding how much prior acquired knowledge the reader will need.

For scope, I think about a course I taught at a college. It applied high-school math, including basic algebra, for making business decisions. The prerequisite math knowledge was clearly spelled out in the course catalog and repeated in the syllabus. The students were mostly seniors, adults aged 20 to 22.

I will never forget the student who rejected the idea of prerequisites, declaring in class, If you expect me to know something on your test then I expect you to teach it to me!

The remark comes to mind when I write documentation. Should I assume the reader knows nothing? Should I start all the way back at 1 + 1 = 2? Of course not; yet, the writing must begin somewhere along the path toward better understanding.

Over-explaining risks insulting the reader’s intelligence. Over-expecting (under-explaining) risks discouraging the reader. Choosing a good balance should humble the writer.

For style, the choices range from terse to loquacious. My preference leans toward a conversational tone illustrated with short, worked examples showing the results of calculations and procedures. I have encountered online experts who disagree. They insist upon restricting documentation to a minimal recitation of correct usage.

For both scope and style, then, one might well paraphrase the opening song in Meredith Wilson’s musical play, The Music Man, You Gotta Know The Territory. The writer of documentation wants a sense of empathy for the reader. The very fuzziness of the concept heightens the challenge for technical writing, that oh-so-not-fuzzy domain.

What is the right thing to do when there is no clear way of knowing for sure? The answers are three: do the best you can; forgive others who do it differently; and forgive yourself for what doesn’t go quite right.