The geometry of technical documentation
Writing only needs two dimensions
Software documentation is about building software, and building involves geometry.
For example, when you look at some common criticisms of documentation —
- “The text is not clear!”
- “Information is missing!”
- “The content is disjointed! No matter how much I read, I just don’t get it.”
— you’ll see how thinking geometrically can solve these problems.
For the first two criticisms, you need only simple lines and squares. The third requires triangles and a bit more math.
Writing horizontally — the sentence
There is a horizontal component to writing an English text — horizontal in a purely left-to-right direction: the sentence.
We balance everything on that horizontal line. We leverage clarity, readability, and style. Spelling and grammar require zero height. For a line to remain single-dimensional, it must be concise, accurate, understandable, and unambiguous.
These are the basic axioms of technical sentences. Other forms of literature — like a novel — might drop the rule of non-ambiguity; poetry redefines or just ignores readability; etc.. But for a sentence to be successful within a technical document, it must follow this strict horizontal set of laws.
Thinking diagonally — the paragraph
The most perfect sentence does not always contain the best content. On its own, a sentence is abstract: It may be clear, readable, and so on, but it says nothing. A line is nothing more than syntax. And attaching lines within a single dimension merely extends the line off the page.
But when you start stringing thoughts together, you start switching direction, moving lines diagonally. Towards the paragraph.
Content — or meaning — breaks the one-dimensionality of the horizontal. Meaningful content slants the writer and reader away from the line: We must now get our text to say something — not only well or accurately — but meaningfully.
Consider this:
“ … judo experts searching for judo techniques might be most interested in advanced techniques … ”
Perfectly horizontal. But banal. It needs to be fleshed out. We need to start plotting points off the horizontal axis, to start attaching lines in all directions — up down sideways slanted. This is the second dimension.
What are the rules of the paragraph? Mostly the same — clarity, correctness, understandability — but it’s no longer about language. It’s about ideas and the order of those ideas. We ask, Is the content — the concepts, ideas, facts — clear?
It’s also about readability and reading — Is the text engaging? Does it flow?
We write and read from sentence to sentence, from sentence to paragraph, from paragraph to paragraph. With this second dimension, our lonely sentence above is given meaning, context.
“The ideal of modern search is smart search — highly relevant results, tuned specifically for each user. For example, judo experts searching for judo techniques might be most interested in advanced techniques; beginners need to learn how to get started.”
Documenting vertically — the page
The page is the vertical component. While the horizontal and diagonal span in all directions, thus plotting our well-written ideas on a blank page, the end result is the page. The technical writer needs to be aware of the math: Does the sum of these lines (and spaces) serve the reader’s needs?
To start with: The page is greater than its parts. Perhaps we can add weight to our geometry: the weight of the sentences and paragraphs that inform the page.
With the page, we ask new questions. We look at the whole. We take a step back. Have we covered the subject? Let’s say we start our page with X and Y — when we reach the bottom, are we still talking about X and Y? have we said all there is to say about X and Y? Is the page self-sufficient, or is there something missing? Is there too much detail, is it too long? Maybe something can be removed, or a new page added.
Let’s look at the above text about Judo. But this time as part of the vertical order of the page. What is it talking about? “Search”? What is “modern” search? What is “relevant” and “results”? For the sentence to have its most successful impact, the page needs to create context (or at least point to where that context exists), and it needs to be conscious of its terminology and capacity / concerns of its readers.
The perfect page, however, is still not enough
Perfect as it is, we are not finished. The page — the vertical — raises other questions. When do we use the information on the page? Where does it fit in, in the larger whole? Should we do what the page tells us to do, and when? Are there alternatives?
Even more difficult are questions of shared content: Some paragraphs and pages relate to other paragraphs and pages. Should we break up the perfect page to favor other ways of organizing content, like centralizing information. And is it OK to sometimes repeat content?
Beyond the page
The breadth of technical documentation goes beyond the page, but it remains two-dimensional. Lines are not only about their own linearity — they also form squares, triangles, and circles — really useful geometrical two-dimensional objects that we can use to improve our documentation.
Before going there, let’s respond to some of the common criticisms mentioned at the start.
- “The text is not clear!”
Text that is Not Clear can be resolved horizontally, with a bit of rethinking in the slanted diagonals. If you are asking, Has this particular thought (paragraph) been clearly expressed? That’s both a horizontal and diagonal concern.
- “Information is missing!”
With Missing Information, we need to rethink the page, the vertical. The resolution is often a rewrite — adding text, removing text, re-wording, reorganizing. We need to focus on the lines, and their three directions — the sentences, paragraphs, and page.
- “The content is disjointed! No matter how much I read, I just don’t get it. I’m calling support.”
Hmm …
Disjointed content cuts deeply. Getting this right is the squared-circle of geometry. The holy grail of documentation.
Luckily, it too can be solved geometrically.
Circles, Squares, Triangles
We don’t want circularity.
Circularity means readers are going in circles looking for answers. Sometimes the text contradicts itself, or repeats itself without ever making sense, or links back to the same page — over and over and over again, the very same sentence, with no way out, back to the beginning, we don’t want circularity, …
How do we help the reader break out of that circle? We don’t write in circles…
What about the square?
Surely, if our documentation covers the “four corners” of a subject, we’ve done our job as technical writers. We’ve created an overview, tutorials, examples, and a formal reference page. We’ve got the perfect square — a self-contained, perfectly organized website, with all the right content.
But maybe not. I would worry, at this point, if our square hasn’t made us complacent. I’ve seen a lot of good documentation out there, many of it perfectly clear and organized and not successful. Its readers are either frantically looking for information and not finding it, or they are not reading anymore. Instead, they are googling, hacking, and calling support.
And they are building far less of our software — going below and beneath what our software is capable of offering. Because it takes too much effort. The math is too great. It’s not worth going any further.
Building software with triangles
The triangle is a powerful architectural shape. It forms the structural basis of all buildings and bridges. And it is not about architectural drawing: The triangle is a physical reality — structures are built using physical matter in triangular shapes.
For the technical writer-turned-geometer, a triangle is a two-dimensional way to think about his or her craft. Already we have the sentence, paragraph, and page — the three sides of a triangle. As such, the triangle is a microcosm of the whole — we can use these triangles to start building an understanding of the software. Start, I repeat.
Documentation builds software, and the triangle is about building. There are two ideas behind this:
- A page is merely one triangle among many.
- Many triangles are needed to build something solid.
These two statements should push us out of our comfort zone and force us to think more globally about what we and our readers are trying to build together.
Maps — Then greatest of the two-dimensional
Do we really write in only two dimensions? Do we need more? If we think of maps — street maps, elevations, land usage, populations, climates, and so on — all of which are essentially two-dimensional representations of the “real world”; if we think about how they combine to help orient and teach us, we can sincerely wonder whether we need anything else.
[Note to self: last sentence could use some horizontal love.]
So … if we think of maps, two dimensions seems to be enough.
Do we need to add a third and fourth dimension? We already have that, we live in it: three-dimensional space, with time-constraints, constitutes not only the world in which we live but the one in which we build software. To get from point A to B, a map is sufficient: we only need take out our folded map or smartphone’s GPS.
But has the map metaphor taken us to another kind of complacency? Have we forgotten the unanswered question above, about content being disjointed? How do we know where to go, and when. Where is the wisdom? What about the holy grail? Where is the holy grail?
At the Intersection of its pages
We are walking through a city. We step into its buildings and neighborhoods. And as we interact with its space, we build structures.
Surveyors use triangles to define space. Joined and overlapping triangles create location. With precision, these locations help us map out the world. Aligning and combining multiple maps creates a dimensionality that more or less resembles the real world. Flat, yes — but fully represented.
Each individual page in software documentation can be combined with one or more pages to create a full understanding of a single feature. Good technical documentation is ultimately a question of set theory: Software is not built at the individual page, but at the intersection of its pages. No one page is sufficient. What is required is that content be found easily, and that it can be combined to create the illusion of unity, to help developers build their unique universes.
