An Engineer’s Best Tips for Writing Documentation Devs Love
It’s fun to watch an enthusiastic speaker sharing what they’ve learned. And at the PyCon 2022 conference earlier this year that speaker was Mason Egger, an engineer turned lead developer advocate at Gretel.AI, a platform offering synthetic /privacy-protecting data.
Prior to Gretel, Egger was a developer advocate and community author at DigitalOcean, where, he told the audience, “I learned a lot of everything I’m about to teach you today.”
Among others things, Egger spent every Hacktoberfest contributing documentation, and Egger’s slide credits the staff of professional editors employed at DigitalOcean for giving him expert guidance.
“If you’ve never seen or used DigitalOcean’s tutorials, they’re fantastic,” Egger told his audience. Indeed, at TNS, we’ve noticed how DigitalOcean’s docs are often much more comprehensible compared to those provided by the larger cloud providers on the same subjects. “There are a lot of great people there that taught me a lot about documentation.
“And now I want to share that with you.”
Reaching Real-World Goals
Writers should value their readers’ time — and always try to get to the point.
Kurt Vonnegut once advised fiction writers that to speed things along, every character should want something, and perhaps analogously, Egger’s first tip advises stating a goal, clearly, that the documentation will help its readers achieve. “Don’t spend time grandiose-ing over your tech,” Egger warns. “If developers want to read a novel, they’ll go and read a novel! Developers are here to get things done.”
So in the event you do include gushing paragraphs of product-touting grandiosity, “They’re just going to skip over that anyway.”
And because of this, Egger believes examples should always show actual real-world problems – since so many readers will be jumping straight to your code samples.
Egger’s audience laughed when he’d asked, “How many of you have read the explanation on every Stack Overflow you've ever Googled? How many of you have scrolled mid-page down, and only just looked at the answer — and didn't even read the text underneath it? Yeah, raise your hand — I've done it too."
Writers should value their readers' time — and always try to get to the point.
"People skip the text! They go to the code! So make sure that you're using real-world problems for it..."
Keeping those busy readers in mind, Egger later said his most important tip was to always verify your instructions before publishing documentation.
"The only thing worse than no documentation is incorrect documentation," he said. "Because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time."
Egger teased the audience with the scenario of instructions that only work on the machine of the documentation's author. The solution? Testing in another developer environment, and also having someone else work through your documentation.
In fact, Egger even believes documentation should also always be organized so it's easy for readers to scan through it for specific bits of information — including headings and subheadings, and with library names highlighted in bold.
"This 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 made it to your documentation and they don't get the answer within 30 seconds — they're going to go to Stack Overflow."
"The only thing worse than no documentation is incorrect documentation,"
Egger believes the average web site visitor spends about six seconds on a site. "They click on it, they look for what they need, if it's not there they're gone. That happens all the time."
At this point in the talk Egger seems to be echoing another common piece of advice given to fiction writers: "Do not tell people what your library does, show people...."
And to help with that demonstration, Egger reminds his audience to choose meaningful variable names. "Foo and Bar are useless," Egger says. "They need to go! Stop using them! They mean nothing."
Later Egger jokes that he feels so strongly about this that getting rid of Foo and Bar "will be my campaign slogan when I run for president."
Inclusive and Readable
In April the Associated Press released a new chapter on "Inclusive Storytelling" in the next edition of its stylebook. And Egger shared his own ways to write inclusive documentation — starting with just avoiding alienating terms like "noobs" or even judgmental words like "simple" or "easy," since what is 'simple' or 'easy' to someone might be challenging to someone else.
"You'd be surprised how many people get turned off by seeing something that other people tell them is simple, and then it's not simple to them. It turns them off the entire project."
Gendered language should also be avoided, and one easy way Egger suggests is just using second-person pronouns like "you." And Egger drove the point home by joking that as a Texan he also likes the word "y'all" when a second-person plural pronoun is required. At the virtual All Things Open 2021 conference, Egger even gave a 12-minute talk arguing this familiar Texas contraction also makes documentation and communities more inclusive.
"You'd be surprised how many people get turned off by seeing something that other people tell them is simple, and then it's not simple to them."
One easy form of inclusivity is simply making sure documents can be understood by all. Egger advises aiming for simpler reading levels — he shoots for third grade — and avoiding "SAT words," that is, obscure words relegated to academic tests "that nobody uses in regular vernacular any more..." But similarly, Egger also recommends avoiding excessive jargon understood only within a specialized group. (Egger points out that "Jargon itself is jargon, which I think is hilarious.") At one point Egger offered a quick aside that could serve as a handy catch-all summation:
"Write the way that people speak, and they'll be able to use your docs a whole lot better."
In fact, Egger advises assuming an audience composed 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 not be familiar 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. "Tech has way too many acronyms," another slide points out. "We even have some acronyms that some 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 tech because of the acronyms," Egger told the audience with a laugh. "And I would like to see them all go away. At least in beginner-focused content."
Like the AP Stylebook, Egger advises also writing out 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.
