Documentation Awesomification

Principles for writing technical documentation that we arrived at after co-editing our entire team’s docs.

How We Got Here

Devs aren’t always incentivised to treat documentation as a very important part of their job, which is how we get into this self-inflicted cycle of pain and misery trawling through each other’s confounding notes.

And even that is a blessing, because indeed, to even have documentation is a blessing.

What with some work isolation and knowledge gaps being unavoidable, and often no dedicated technical writing resource available, it’s no wonder internal documentation from one team can sometimes turn into a sprawling mess seemingly written by a cacophony of voices.

Hopefully I don’t have to tout the benefits of good documentation to convince anyone of their importance, but here are some big ways that I’ve seen it pay for itself many times over:

• It serves as a resource that teams can point to when faced with common user queries, drastically reducing support effort.
• It introduces new devs to the product, and forms a key component of the knowledge transfer process by serving as an anchor.
• It is a record that managers can refer to repeatedly to keep up with the technical details of the many products and services they are responsible for.

Still, sinking resources into writing good documentation is sometimes seen as a luxury reserved for public-facing products. Often, it is treated it as more of an afterthought, a bonus work item to assign devs if the technical work is done before the sprint is over.

Luckily, we do care about our documentation, and invested no little time in bringing it up to standard.

Prime Directive

Having waded through a mind-boggling number of pages of varying documentation quality and colourful writing styles, here is our number one guiding principle for writing technical documentation:

With very rare exceptions, reading documentation has never been enjoyable. The experience can feel so unrewarding and frustrating, no wonder there’s that joke about devs avoiding a 5-minute read of the documentation in favour of spending hours hammering away fruitlessly at the code instead.

Therefore, assuming we’re not at a level where we’re aiming to regale and amuse our readers, the first aim of the documentation should actually be to get them to stop reading it as soon as possible. (For this reason, we always have contact information at the top of the documentation - readers are immediately granted an out, so that if at any point they are too annoyed, they know where to find the humans. Sheer social anxiety should hopefully help them afford at least a glance at the rest of the documentation…)

Since the aim is to minimize the amount of time readers spend in the documentation, a corollary of the prime directive is:

You’d be surprised (or perhaps you wouldn’t) at how often documentation can come off as some dev journaling about their project, like they’re writing flavour text for legendary equipment in some MMORPG. Even worse, sometimes it’s taken as a grand opportunity to talk up the importance and usefulness of their tool - wasting their own and everyone else’s time.

Hence after co-editing pages upon pages of sentences disturbingly light in information density, we decided that each line had to justify their place in the documentation by providing something actionable, something that could reasonably change the reader’s behaviour after having read it.

No interesting tidbits or cool facts or irrelevant statistics would be allowed to distract from the documentation’s singular purpose - to quickly answer questions a reader has before reading the documentation, and hopefully also those that may come up in the course of reading the documentation.

Anti-patterns

With that, let’s look at some examples of what we saw, and what we’d recommend instead.

Backstories & Origin Stories

There are introductions, and then there are introductions. Just like when you’re introducing yourself, you should err on the side of leaving the audience wanting more, rather than finishing your piece and looking up to see that what few people still hanging around are leaning back.

Data Format

Readers should absorb content with as little effort as possible. Don’t make them hunt for information in the paragraphs until their eyes swim.

🙃

“For example, Scanner 9S will check that plug-in chip C1 version is >=1.23, chip C2 version is >2.13 and <3.12 unless condition X, chip C3 version is >4.21 and <=4.32 if condition Y and Z, and …”

🙂

Scanner 9S plug-in chip version requirements:

Explanation

I wish I could say that the example above was contrived, but sadly we saw poor formatting of data many times in our awesomification project - lines and lines of text droning on with little consideration for the mental health of the reader, the author seemingly having just regurgitated their thoughts in an unchecked stream from brain to keyboard, rather than thoughtfully curating and designing pieces of information to be neatly and smoothly slotted into their readers' minds.

Data Format II

It’s also good to employ strategic paragraphing, and some syntax highlighting. In fact, treat the documentation as a sort of slightly more accessible piece of code needing helpful arrangement and presentation differentiation in order to make it conducive to human interpretation. There’s no point to documentation that only the author understands - at least with code, you could argue that it’s performing work as long as the machine understands it.

🙃

There are five types of plug-in chips, namely Attack, Defense, Support, Hacking, and System. Chips can range from level 0 to level 8, though not all chips will be available at multiple levels. In order to make sure that you are not equipping a bad chip, we recommend that you review the authentication state of each chip prior to deployment in combat. The possible values of the authentication state are: ANONYMOUS, RECOGNIZED, SESSION, AUTHENTICATED, MACHINE, FOREIGN. To view or update the minimum authentication state recommended for a particular chip, use the Chip Verifier program and select “Chip Authentication”, then check the value of CHIP_AUTH_STATE. If your chip is of mysterious or unknown origins, it will be necessary to request additional processing capacity from the Bunker to perform a more in-depth analysis. To submit your request, visit https://automatabunker.ai/portal/display/management/scannerType/overrideRequests/AUTH#processing or https://62.75.6e.6b.65.72.0a/SYSTEM/settings/unitdata/androidType/SCANNER/9

🙂

There are 5 types of plug-in chips:

• Attack
• Defense
• Support
• Hacking
• System

Chips range from level 0 to level 8, though not all chips have multiple levels.

Reviewing the authentication state of each chip prior to deployment in combat is recommended. Possible values of authentication state include:

• ANONYMOUS
• RECOGNIZED
• SESSION
• AUTHENTICATED
• MACHINE
• FOREIGN

To view/update the minimum authentication state required for a chip:

1. Select the Chip Verifier program.
2. Select Chip Authentication.
3. Confirm the value of CHIP_AUTH_STATE.

Chips of mysterious or unknown origins will require additional processing capacity to perform a more in-depth analysis. To make a request from the Bunker, see:

• Bunker Override Requests Portal
• Android Direct Link Settings Access

Explanation

The reader should be able to, upon reading the first few words or so of the paragraph, be able to determine if they want to bother reading the rest of it. So be sure to segment your text in that fashion.

Lists of items should be presented as bulleted lists, especially once you get a count of three or so. Instructions should always appear in a numbered list where possible - few things are as frustrating as switching tabs and trying to hunt down where in the instructions you left off last time.

Unless there is some strong reason for keeping long/ugly links in explicit form, hyperlink some helpful, descriptive text instead. And be sure to arrange them neatly so you don’t end up in a sea of clickable blue - in the sad example, I don’t even feel like parsing what the links are and if there are one or two of them. You can imagine how bad it gets when more of them come into the mix.

Finally, be sure that you’re not dragging on some sentences unnecessarily, especially those long ones with more than three commas, because again it’s exhausting enough having to read documentation without having to go through paragraph-length text that keeps going on and on elaborating on something for so long that by the time you get to the end of it, you can’t even remember what it was talking about at the start - which is especially bad if it’s on an unfamiliar/intimidating subject - remember to give your readers plenty of opportunities to pause, process, and save their progress!

Data Format III

🙃

🙂

Explanation

Hopefully this one is easy to see - a sea of symbols is better than a sea of words, especially when the table gets much bigger. The only caveat here is that the symbols should be easily distinguishable by shape as well, because there are those among us for whom discerning by colour is not an option.

Linear Instructions

Aim to have the reader’s eyes only move from left to right, up to down. The more you make your readers scroll all over the place, darting around to piece things together, the more you’ll lose them.

🙃

To onboard a new Scanner Type, follow the following instructions carefully:

1. Go to Scanner S Dashboard and click on Add New Android.
2. If you are using Browser B1, skip to step 3b. Otherwise make sure proxy settings are correct.
3. Fill in fields X and Y, then click Next.
   a. Enable option O3.
   b. (also do this if you want automated scanning jobs set up)
   - if android framework is F1, click on p, then fill in q and r, then…
   - if android framework is F2, fill in q only, then…
4. Click submit.
5. Your onboarding is complete!

Proxy Settings
Browser B2: If on AndrOS, set system proxy settings (with System Preferences)…
Browser B3: Set Host and Port to H1 and P1 through the browser extension…

🙂

Onboarding

1. If using Browser B2 or B3, check proxy settings:
   Proxy Settings
   Browser B2: If on AndrOS…
   Browser B3: Set Host and Port…

2. Go to the Dashboard and click on Add New Android.

3. If using Browser B2/B3, fill in fields X and Y, then click Next. Enable option O3.

4. If using Browser B1, or setting up automated scanning jobs:
   a. Framework F1: click on p, then…
   b. Framework F2: fill in q, then…

5. Click submit.

Explanation

It is critical to get this right for instructions. Trying to walk through some of them for verification as part of the co-editing process was endlessly frustrating. In the sad example, when step 2 mentioned making sure that the “proxy settings are correct”, said proxy settings instructions were at least three scrolls away, nowhere in sight from where it was first introduced. And neither did the instructions mention what or where they might be - it had to be inferred after investing time into reading most of the document.

This is frankly quite unacceptable if you wish to keep your hold on the reader, so in the glad example I relocated the proxy settings right under where they are introduced - it’s not like they are needed at any other point either, so that is the correct and convenient place for them.

More importantly, the instructions were rearranged in such a way that the reader need at no point scroll back up to a previous step, or risk skipping important information hidden in a sub-step somewhere. At each step, the reader has all the information they need in order to complete that step, and can proceed without any continuity issues. If your instructions are so complicated that they need employ multiple redirections, perhaps it is time to split things up into multiple sets of instructions.

Also, “Done!” is not a step. Don’t do it. Remember the corollary!

Real Estate

Don’t spread minimal content over multiple pages just to generate a handy link for each of them (clicking is a high-cost user action). Especially not for each FAQ answer. Anchor tags exist! ‘Nuff said.

Distracting Elements

A picture takes up a thousand words. Don’t add cute images with zero actionable content in the middle of your documentation. There’s no need for decorative anything.

Nitpicking

Grammar and spelling should be pretty basic stuff, though it can be hard to keep all the product stylizations consistent, I get it. But if you’re aiming to write world-class documentation, the least you can do is get names right. That said, it’s not like this is where the most value of your work is going to be generated, so I’d say just try to pay some attention to it, so nothing too egregious pops up.

Thesaurus Abuse

Never use a long word where a short one will do.
  ― George Orwell

Using big, fancy words for narrative effect is one thing, taking up some poor dev’s RAM unnecessarily while transferring technical data is another. And even with smaller words, why say many word when few word do?

Conclusion

If you’ve been entrusted with writing documentation, accept it as the sacred responsibility that it is 🙏 Your labours may very well bear fruit as some dev’s Virgil in their unnerving journey through Inferno someday. As thanks to all the teachers and mentor figures who have helped you get this far, pay it forward and awesomify your documentation.