What makes docs beautiful?

Docs are often thought of as a purely functional artifact, a packet of content that, when it works, it’s not remembered at all. Those who consume documentation, however, can tell whether a manual or docs site pleases our mind and senses in ways that others don’t. We know the feeling of a page that lands and the feeling of a page that drags.

Now, if we agree that docs can be a product, why not seek to build them in a way that pleases consumers? If docs are the entry point for products, shouldn’t they produce a positive feeling that makes users return to them more often and trust them more? Docs that make users feel empowered, or that leave them with learnings. Docs that heal.

The question of what makes documentation beautiful is an important one, especially in a time when docs are at risk of being mass produced by LLMs that have neither the taste nor the ability to discern good docs from bad ones. I’m writing this post to open up the question to debate, and perhaps to provide myself with inspiration.

In technical writing discourse, beauty is almost always absent

I found very little on the topic of beauty and documentation. The concept of beauty is absent from professional discussions; at most, folks will point to Stripe docs or mention how nice the Viam docs site looks, without being able to put a finger on what it is that makes them beautiful. There are, of course, many tangential conversations and ideas, like in the field of human-computer interaction.

For example, in a highly quoted paper by Tractinsky et al., What is beautiful is usable, the authors found a strong correlation between perceived aesthetics and perceived usability that got stronger after people used the system. In the discussion, they quoted Kristina Hooper’s Architectural design: an analogy, a chapter from the seminal book User Centered System Design, edited by Donald A. Norman and Stephen W. Draper in 1986.

The design of information systems […] is often compared to architectural design. […] Hooper wrote that architectural analyses emphasize the facades of buildings for several reasons. Among those reasons are that the facade is the introduction to the building: “This is what most people experience directly”. In addition, the facade can serve as a “membrane between the inside and the outside, and its purpose is to articulate the relationship between the two.”

Among technical writers, Daniel Procida speaks of quality as a key property of docs, differentiating between functional quality and deep quality, the latter of which includes feeling good to use and being beautiful. Procida makes deep quality conditional on functional quality; in other words, you can’t have beautiful docs without first having docs that work, something I also defended in the Docs hierarchy of needs. Lately, Ellis Pratt pointed me to Vitruvius, who named three pillars of architecture: Durability, utility, and beauty. The third is the one we’ve neglected.

Function trumps form all the time in our craft. One writer in the Write the Docs community told me: “If docs are trying to be beautiful, they are failing in their purpose.” With time, though, I’ve come to suspect that what we call beauty or good UX for docs exists and matters, and that it has less to do with graphic design and visuals and more with the way documentation is produced, edited, and organized. Much in the same way an ordered line of books on a shelf produces a pleasant feeling, the sight of structured and well presented documentation does, too.

And this is where a writer from my home country, Italo Calvino, enters the frame.

Recovering Italo Calvino’s Six Memos for the Next Millennium

In 1985, shortly before dying, Italo Calvino wrote a series of lectures on the future of literature, Six Memos for the Next Millennium. Each lecture or memo focuses on a different literary quality. Although it’s hard to confirm whether Calvino, who also dabbled in science fiction, thought of technology when writing his lessons, I’m sure that he didn’t ignore that people would read differently in the 21st century also because of it. That’s why I find his ideas translate well to technical writing, which Calvino might have regarded with curiosity, even if ironically.

The six literary qualities that Calvino planned on presenting at Harvard were: Lightness, Quickness, Exactitude, Visibility, Multiplicity, and Consistency. The names resonate so strongly with what I think are also docs qualities that I could not resist the temptation of drawing bridges between each lesson and what it may mean for technical writing, without trying to shoehorn them onto documentation and its requirements. I think Calvino wouldn’t have minded.

Lightness: Docs that grin and remove barriers

Calvino’s first lesson is on lightness, an adjective that we would not dare ascribe to docs, let alone literature. Calvino was quite conscious of the potential reaction to his choice and took great care to contextualize what lightness meant to him. In the process, he got to comment on the lightness of the cloud compared to the heaviness of hardware:

Software cannot exert the power of its lightness except through the heaviness of hardware, but it’s the software that’s in charge, acting on the outside world and on machines that exist solely as functions of their software and that evolve in order to run ever-more-complex programs.

In documentation, we could say that lightness is the ability to explain the heaviest technical concepts and procedures without burdening the reader. Lightness is clarity through the avoidance of opacity and inertia. Docs are beautiful when they express the promise of knowledge without its burden. Docs that grin are light while being accurate.

Quickness: Docs that don’t waste your time

Beautiful docs get to the point fast. They do not need to wander, because they’re written by someone who knows both the subject and the audience. They can find the most efficient shortcut to the intended reaction or insight. Part of that quickness in telling the story is enabled by repetition (Every Page is Page One, anyone?). In Calvino’s words:

The craft of oral storytelling in the popular tradition is shaped by functional concerns; it omits pointless details and insists on repetition […] Part of a child’s pleasure in listening to stories is in the anticipation of certain kinds of repetition: situations, expressions, stock phrases.

Docs should be formulaic and consistent while telling the short story of how to do things. What technical writing, poetry, and code can share is conciseness. Docs that say things in one sentence instead of overloading the reader’s mind with meandering explanations are more pleasant to our brains. Docs are quick when they don’t waste time.

Exactitude: Docs that refuse to be approximate

This quality should not come as a surprise to technical writers. We utterly enjoy precise and accurate documentation. We value the presence of exact values. A wave of pleasure runs down our spine when we spot the right word for its meaning. Documentation’s moral imperative is to use language as a tool for conveying knowledge with the least friction.

For me, exactitude means above all three things:

1. a well-defined, well-considered design for the work;
2. the evocation of clear, sharp, memorable images;
3. a language that is as precise as possible in its choice of words and in its expression of the nuances of thought and imagination.

[…] It seems to me that language is always being used in a loose, haphazard, careless manner, which I find unbearably annoying.

The most exact word in the world cannot rescue a page that sits in the wrong place, under the wrong heading, inside the wrong structure. Exactitude in docs begins with knowing what a page is for, and only then with how it is written. Docs are exact (and beautiful) when every level of the work, from sitemap to admonition, refuses to be approximate.

Visibility: Docs that help us recreate knowledge

When Calvino wrote about visibility, he commented on the quality of literature that allows readers to see things in their minds, effectively imagining things. Perhaps worried by the impending advance of multimedia noise, he defended the evocative power of words in literature (and, by extension, in all forms of written communication):

If I have included visibility in my list of qualities worth preserving, it is because we are in danger of losing a basic human faculty: the power to bring visions into focus with our eyes closed, to cause colors and shapes to spring forth from an array of black characters on a white page, to think through images.

Docs are beautiful when conceptual docs let the reader see the architecture, or when a tutorial lets them see their own hands on the keyboard. Diagrams and screenshots help, but they often compensate for prose that failed to produce an image on its own. Docs are visible when the reader can close their eyes and still see what the page described.

Multiplicity: Docs that contain multitudes

Calvino thought that “every life is an encyclopedia” and described ambitious works of literature as artifacts that could hold many kinds of knowledge at once, weaving voices and registers into a single body without collapsing them into one. That ambition translates well to docs, which are inherently plural through different content types.

As science begins to mistrust general explanations and solutions that are not narrow or specialized, the great challenge for literature will be to learn to weave together different kinds of knowledge and different codes into a pluralistic, multifaceted vision of the world.”

Docs are beautiful when they aspire to greatness. They achieve it by covering the entire spectrum of users’ concerns from multiple angles, like the ones I introduced in the Seven-Action Documentation Model. A fellow tech writer, Kevin Kuhl, compared it to a beautiful mathematical proof, which is beautiful not because it’s correct but because it connects all the bits. Beautiful docs hold distinct voices that share the same shelf.

Consistency: Docs that flow as expected

Calvino died before he could write his sixth lesson. We can only guess what he would have said about this one, but we know that if there’s one quality every technical writer would attribute to beautiful documentation, it’s consistency. We enjoy it when docs flow predictably and provide us with nuggets of information where we expect them to be.

You find consistency in style guides, linters, and glossaries. You also find it in consistent UI behavior. But the consistency that makes docs beautiful is the sense that every page came from the same mind, that the author knows what the product is and what the reader aims to do. Docs are consistent when the reader doesn’t notice the seams.

Six words to escape docs brutalism

I brought Calvino’s memos here as a spunto, an Italian word for a small thing that starts something larger. We should have a conversation about what makes docs beautiful. Our craft has hyperfocused on function for so long that the discourse has gotten brutalist. We argue about tools and commas but don’t ask what makes users return to the docs.

Technical writing is a literary genre, too. A genre can be beautiful without pretending to be a novel. A reference page can be exact in ways a poem cannot. A tutorial can be light in ways an essay cannot. Calvino gave us six words to start with, and perhaps yours are different. The rest is ours to write, but first we have to start caring about it.