An engineer’s top tips for writing documentation that developers love – The New Stack


It’s fun to watch an enthusiastic speaker share what they’ve learned. And at PyCon Conference 2022 earlier this year, this speaker was Mason Eggeran engineer turned lead developer at Gretel.AIa platform providing synthetic data/protecting privacy.

Prior to Gretel, Egger was a developer advocate and community author at DigitalOceanwhere, he told the audience, “I learned a lot of everything I’m going to teach you today.”

Among other things, Egger spent every hacktoberfest contributing Documentationand Egger’s slide credits the staff of professional editors employed at DigitalOcean for providing expert advice.

“If you’ve never seen or used DigitalOcean’s tutorials, they’re fantastic,” Egger told his audience. Indeed, at TNS, we have noticed how DigitalOcean’s documents are often much more understandable compared to those provided by the largest cloud providers on the same topics. “There are a lot of great people there who taught me a lot about documentation.

“And now I want to share this with you.”

Achieve real-world goals

Writers should value their readers’ time – and always try to cut to the chase.

Kurt Vonnegut once informed fictional authors only to speed things up, each character should want somethingand perhaps analogously, Egger’s first advice advises to state a goal, clearly, that the documentation will help his readers reach. “Don’t waste time bragging about your technology,” warns Egger. “If the developers want to read a novel, they will read a novel! Developers are there to get things done.

So if you include gushing paragraphs of grandiosity touting the products, “They’re just gonna skip it anyway.”

And for this reason, Egger believes that examples should always show real, real-world issues, because many readers will jump right to your code examples.

Egger’s audience laughed when he asked, “How many of you have read the explanation for every Stack Overflow you’ve googled? How many of you scrolled down the page and just looked at the answer – and didn’t even read the text below? Yeah, raise your hand – I did that too.”

Writers should value their readers’ time – and always try to cut to the chase.

“People are skipping text! They’re going to code! So make sure you’re using real-world problems for that…”

Keeping those busy readers in mind, Egger later said his most important advice was to always Check your instructions before publishing the documentation.

“The only thing worse than no documentation is Incorrect documentation,” he said. “Because without documentation, I’ll look elsewhere. Incorrect documentation is wasting my time.”

Egger teased the audience with the script of instructions that only work on the documentation author’s machine. The solution? Test in another development environment and have someone else work on your documentation.

In fact, Egger even thinks that documentation should always be organized so that it’s easy for readers to to analyse browse it for specific information – including titles and subtitles, and with library names highlighted in bold.

“It goes back to that Stack Overflow thing,” Egger said.

For the same reason, Egger advised a table of contents. People scanning a document “are trying to solve a very specific problem, very quickly. If they’ve reached your documentation and they don’t get the answer within 30 seconds, they’ll go to Stack Overflow.”

“The only thing worse than no documentation is Incorrect Documentation,”

Egger thinks the average website visitor spends about six seconds on a site. “They click on it, they look for what they need, if it’s not there They left. It happens all the time.”

At this point in the lecture, Egger seems to echo another common piece of advice given to fiction writers: “Don’t tell people what your library does, To display people….”

And to aid in this demonstration, Egger reminds his audience to choose significant variable names. “fooo and Bar are useless,” says Egger. “They have to go! Stop using them! They don’t mean anything.”

Later, Egger jokes that he’s so attached to it that getting rid of fooo and Bar “will be my campaign slogan when I run for president.”

Inclusive and readable

In April, the Associated Press published a new chapter on “Inclusive Storytelling” in the next edition of their stylebook. And Egger shared his own ways of writing understood documentation – starting with avoiding alienating terms like “noobs” or even judgmental words like “simple” or “easy”, because what is “simple” or “easy” for someone can be difficult for someone else.

“You’d be surprised how many people get discouraged by seeing something that other people tell them is simple, and then it’s not simple for them. It distracts them from the whole project.”

Gendered language should also be avoided, and an easy way suggested by Egger is to simply use second person pronouns like “you”. And Egger drove home the point, joking that as a Texan, he also likes the word “y’all” when a second person plural the pronoun is required. During the All Things Open 2021 virtual conference, Egger even gave a 12 minute conversation this colloquial contraction of Texas also makes documentation and communities more inclusive.

“You’d be surprised how many people get discouraged by seeing something that other people tell them is simple, and then it’s not simple for them.”

A simple form of inclusivity is simply to ensure that documents can be understood by everyone. Egger advises aiming for simpler reading levels – he’s shooting for third grade – and avoiding “SAT words”, i.e. obscure words relegated to academic tests “that no one uses anymore in regular vernacular…” But similarly, Egger also recommends avoiding excessive jargon understood only within a specialized group. (Egger points out that “jargon itself is jargon, which I find hilarious.”) At one point, Egger offered a quick aside that might serve as a handy summary:

“Write like people talk, and they can make better use of your materials.”

In fact, Egger advises to assume an audience consisting entirely of beginners, unless you know for sure that your audience is more advanced.

Along the same lines: Avoid figures of speech and pop culture references, which may be unfamiliar to a global audience. While Egger himself loves memes, “you should try to avoid them for inclusive documentation.”

This brings Egger to a pet peeve. “Technology has too much acronyms,” another slide points out. “We even have acronyms some of which have two or three meanings,” Egger told the audience, adding that acronyms can intimidate new learners.

“I spent more time being afraid of acronyms and not using technology because acronyms,” Egger told the audience with a laugh. “And I would like to see them all disappear. At least in content aimed at beginners.”

Like the AP Stylebook, Egger also advises writing the full name the first time an acronym is used. Egger even links acronyms to their definition at the beginning or end of the document.

“There’s nothing wrong with a glossary,” Egger told the audience.

The New Stack is a wholly owned subsidiary of Insight Partners, an investor in the following companies mentioned in this article: Real.


Comments are closed.