© 2024 Reid D. McKenzie, all rights reserved.

Techwriting 101

21 Jun 2017

At Twitter we have regular employee training courses on a number of subjects. These are my notes from our class on writing technical documentation for developers.

What are docs

Anything from diagrams to stained bar napkins. Could be a book, could be a public website, could be an internal resource.

Docs are the way that experts re-visit subject domains. They’re how your customers / other service owners read in on your system. They’re how new hires will start orienting themselves to the Twitter environment.

Why docs

Google study: 1/3rd of all code searches are looking for examples or specific API information.

Django: 120Kl of English, 80KloC. If you haven’t written your docs you haven’t written your product.

Outline

Gonna go over three main sections…

  1. The secret to writing good docs (know thy audience)
  2. Writer’s block
  3. Polishing (patterns & antipatterns)

1. Know Thy Audience

Who is the document you are preparing for? Other developers? Non-technical user? Yourself in six months? An SRE at 2 a.m. when things are on fire? People with no context (far distant team or new hires) and remotes who need to be able to find information without constantly standing on someone.

Common kinds of documents & audiences (think job to be done)

  1. Introductory material
  2. Runbooks
  3. Service docs
  4. Design docs
  5. Cookbooks
  6. Team pages
  7. Troubleshooting
  8. Style guides
  9. Policy pages
  10. Roadmaps

What do your readers know comming in?

Different sets of documentation serve different purposes. What knowledge do they have and what can you assume?

Most developer docs err on the side of assuming knowledge. Lots of possible reasons for this, but it’s an antipattern to be aware of.

What’s the takeaway your document should communicate?

Doesn’t have to be 5pgf MLA format, but you should have a TL;DR or thesis. This helps avoid problems like the interminable FAQ.

Audience Creep

Know the scope of the doc. Often you’ll incrementally expand the vision of the document until it tries to be everything to all people at which point it’s kinda useless.

2. Writer’s Block

JUST. FRIGGIN. START. WRITING.

A metaphor: activation energy. Anything you can do to lower the activation energy encourages the reaction to occur. Once you get into a project you’re “in the flow” and it’s easy to keep hacking/writing, and you want to do whatever you can to stay there.

Forcing functions: pomodoro / the most dangerous writing app etc. Lifehacks and soforth abound here.

Often the way to get started is to just braindump.

2½. The documentation lifecycle

  1. Rapid development - visual artists & cartoonists. You start with shapes and just start doodling, iteratively refining. Someone dumped a wall of text, someone else organized it, someone else added examples… etc.

  2. Feedback - People read it and comment. Someone else goes on-call and has comments / discovers things which aren’t written down. Even comming back to it the next day helps, but really it’s about getting someone with a new context someone else who doesn’t have the same context to look at the code. This is why docbird has code review as part of the workflow, it ensures that someone else has to put eyes on the document. You’ve got to build this into your team’s workflow.

  3. Maintenance - Documentation which isn’t true to the live system is pretty much worthless.

3. Writing really super amazing docs!

Antipattern: docs that aren’t docs

It’s not documentation to tell someone to ask someone else. Guideposts of where to do discovery are helpful but they aren’t sufficient.

Antipattern: nerdview

Defined by the Language Log crowd

Nerdview is the tendency for people with any kind of technical or domain knowledge to get hopelessly stuck in their own frame of reference

Imagine reserving a rental car inline, and being asked to enter a date in DD/MM/YYYY format and getting an error message “Please pick a date greater than today”. Nobody says “greater than today”. This sentence only makes sense when you’re thinking about dates as integral values which you’re gonna be comparing as in a computer system.

This is really just an instance of knowing your audience.

Antipattern: noun piles “crash blossoms” or “garden path sentences”

Just adding hyphenation to clarify qualification can help a lot.

Antipattern: Acandemese/technicalese

Don’t slip into formalism just because you’re writing docs.

Antipattern: slang

Non-english-first speakers exist. We employ lots of ‘em. Know thy audience and try not to over-use slang if only for the purpose of clarity.

Antipattern: Buzzwords

Type-safe! Modular! Parameterized!

Sometimes these help, sometimes these just add volume. Be aware.

Antipattern: Acronymns

Define them! Did you know that we have TSA and ACID at Twitter neither of which mean what you think they mean in common outisde-twitter usage?

Antipattern: Birds

DON’T FUCKING NAME YOUR THING AFTER A BIRD. STOP IT. THE JOKE IS DEAD. IT’S NAILED TO ITS PERCH. IT’S SLID DOWN THE CURTAIN AND JOINED THE CHOIR INVISIBLE. IT IS AN EX-PARROT.

Pattern: Simplicity all the way down

Simple pages

10-20min ABSOLUTE LIMIT on a given page of docs. Some say 5-10min is better… it depends on what your use case is and how you expect your audience to read. Again think what is the job of the document and what kind of attention do you expect your reader to direct to it?

Simple sections

Sections should be single-topic and targeted.

“Tasks not tools”. Title your section in terms of what problem your reader is likely trying to solve, becuase only rarely is your audience reading to lear rather than reading trying to solve a problem. Can you title your question as a question or a gerrund rather than as a spare noun?

Remember that while you may write your docs front-to-back people will tend to discover them via some search tooling, so you shouldn’t be afraid of repetition and certainly not of linking back to things you’ve already written about.

Simple paragraphs

Don’t be afraid of single sentence paragraphs.

Don’t present information that’s better rendered tabularly or as a diagram as prose just because that’s what’s convenient / easy to write from pick your editor of choice.

Simple Sentences

“Someone said that words are a lot of inflated money - the more of them you use the less each one is worth”

~ Malcolm Forbes

Simple Words

The beginning of knowledge is to call something by its proper name

~ Confucius

Coherence vs. Completeness

Your doc should hang together. You should be able to sum up topics. This fits naturally into the context of completeness.

Kinda naturally at odds with Coherence. Completeness is saying everything, and coherence is saying just enough or just what is needed. Same as #shipit vs #berigorous. What are the top three use cases for this doc? What are the next three? Can you hide complexity with links?

You can kinda only keep five things in your working memory at once… three is kinda this nice magical number. Linking is a great way to reference complexity without becomming massively monolithic.

Templates & metadata

Often times you’ll open a document and kinda have no idea who the author was and what the status was and what the changelog was and so on and soforth.

By using templates which provide those empty headings/sections/fields it becomes easier to get it right and write all that down.

Templates also help you be consistent in the structure of your documentation, which means that users can predict and rely on the structure of your content which makes docs more approachable.

Correctness, Maintenance & Culture of Documentation

Formatting & Variation

In lots of docs you have this “wall of text” antipattern. This is particularly bad in confluence because the editor is weak and lines are long.

Formatting helps make the high-level structure of the document easier to understand / visualize / work with.

Lists, boldface, italics and break out boxes help display structure tastefully. BUT DON’T OVERDO IT. If everything has a warning box, your users will ignore all of them and soforth.

asside: Overdoing it. If you can’t simplify the techdocs, it’s commonly a smoking gun that the thing you’re documenting is too complex.

Edward Tuft’s The Visual Display of Quantitative Data.

Pie charts are the worst. Bar charts and tables are better almost universally.

Closing bits