Let’s talk some old school stuff. Technical writing.

The Agile Manifesto rang true for good reason. It reflected what was wrong with hidebound development and why little organizations could outperform larger companies.

It was also a product of frustration, in part to get away from “documentation driven, heavyweight software development processes,” expressed in a glaringly toxic principle in the Agile Manifesto.

“[We have come to value] working software over comprehensive documentation.”

Nope. I can’t agree. True, there are no guarantees of success. Many things can cause a project to fail. One of them is starting development with something other than a word processor.

If you want to hit the target, have a target. You need continuously evolving documentation begun before any code hits a debugger. That’s at odds with human nature. Most developers don’t like writing anything other than code. Give any of us a reason to sideline documentation, the project suffers.

Meanwhile, Artificial Intelligence is gaining momentum in every area. I suspect some of the documentation I’ve been confounded by recently was the product of artificial writing, pun intended.

Too much documentation reads quite well without conveying information. It’s as if it were written by someone — or some thing — with eidetic memory and no idea what the product is for.

Documentation written with an LLM’s care for predicting believable sequences of words may be a treat to the eye. Executives reading authoritative glibness will naturally assume it means something. It must be a wonderful product, send money, and then send more for extended support when problems can’t be solved with the documentation.

You might make the sale with tastes-great-less-filling documentation, but at the cost of a future black eye for your company.

What AI hasn’t figured out

It doesn’t take the story telling skills of a Hemingway to write effective documentation. It’s nicer to read artisanal prose, but esoteric craftsmanship is not needed. Meaning and clear communication is what counts. A few baseline requirements can assure that goal is met.

I’ve taken college courses in technical writing, unfortunately taught by frustrated English Lit graduate students. A shame because technical writing is both important and not a terribly advanced subject.

A few simple edicts will guard against the worst flaws in bad technical writing.

Here are some of my guideposts for crafting documentation. Please don’t tell ChatGPT. I want to keep my edge.

Define concepts and terms

Never assume the obvious is really all that obvious. One of my favorite examples of technical writing is the User Guide for Mellel, a Macintosh word processor.

Everything is explained. The section on character formatting starts with the rhetorical question, what is a character?

We all know what characters are. Confusion is avoided with a simple definition. As it turns out, it’s not as simple a thing to nail down as it was before Unicode. Mellel is used by nontechnical users. The explanation was not wasted.

Control your forward references

Avoid referring to things yet to be discussed. Forward references are a major pain for the reader.

Use them only when needed and always with enough context to get past the topic at hand. Never leave a forward reference unresolved. It might clarify the dangers of forward references if we consider footnote inversion traps, for example, but only if I do two things.

I need to provide enough supporting commentary to cover footnote inversion basics and I need to eventually explain footnote inversion in detail.

If you feel frustrated because I’ve provided no context for this new concept of footnote inversion, then I’ll claim a victory in the war against unsupported forward references.

For the curious, footnote inversions don’t exist.

Always document both do and undo

Never document how to do something without documenting how to undo it. Users will employ ill-considered options and need to get back to square one, or a curious user will try an option to see what it does. That’s the wrong time to discover reversing the decision is either impossible or undocumented.

The power to undo is also a license to learn. Users must not be reluctant to explore. The Hobbit wouldn’t have been half the fun if its subtitle were just “There.” There and back again is a much better story and it’s much better for your documentation, too.

Document side effects

Features that don’t interact are the best. That’s not always possible and the poor documentarian doesn’t get to make that design decision, anyway.

If enabling one feature makes a difference in another facet of an application, document the dependency. If you don’t, you will train your customer base to expect quirks. Real symptoms may be ignored as trouble develops.

There’s a word for documentation leaving surprises for the user to discover — incomplete.

Document workflow impact

Features won’t always be mutually compatible. Some options may prevent otherwise normal use of software. Think how many times you’ve seen “:wq” in the middle of a configuration file. Yep, another user who didn’t realize side effects of the vim text editor’s “i” command prevented “:wq” from saving the file and exiting vim.

Know your writers

Most of all, know your writers and keep them in the loop. Without good documentation, Agile philosophy notwithstanding, you don’t have a good product.

One of the wisest people I ever worked for, Bill Mostyn, had a saying about engineering. “If it’s not pretty, it doesn’t work.”

He didn’t mean crummy aesthetics caused something to not function. What he meant is that if a product didn’t incorporate neatness in its design it was prone to failure and he would not sign off on its functionality.

Part of “pretty” in any product is documentation.

If it’s not appropriately documented, no matter what “it” is, it isn’t as effective or valuable as a competitor’s well documented product.

Something to think about.

And please give me something to think about. Leave a comment, or get in touch with me at carl@carlhaddick.com.

Thanks for stopping by!