#13 Tech Writing for Devs - Part 1
Become a better writer
Hi folks,
Here’s another write up, this time about technical writing. Last year I created a training that teaches developers how to write better technical documentation for platforms and libraries that they build. At Rakuten Tech we are ~5000 people, a big part of the software we build is used by other development teams. Bad UX is bad for business - that’s super obvious for consumer apps (I know, Japanese web design is a bit special, but that’s a different story). Good UX for platforms and libraries means good documentation. Good writing.
…but Why?
Why should I care about technical writing?!
I’m a dev, I write code like poetry! It’s self documenting.
Leave me alone with your READMEs, wikis, javadoc, powerpoint and all that!
— the annoyed developer
Now, the quote is fake. But I’ve seen developers speak clearly though their actions & attitude: I don’t care about writing!
Here’s a real quote:
A platform is 90% documentation, 9% quality & infrastructure and 1% code
— the anonymous architect
We use platforms all the time. Some of us build platforms. You use AWS, eslint, Twilio, npm, Auth0, React, Stripe, etc. to deliver value to your customers. Or you build such libraries, APIs, cloud platforms and tools. Or both. As developers we rely on good technical writing all the time. Without it we’d be unable to use any tool, we’d be stuck in stack-overflow-copy-paste purgatory until the end of times.
Here’s a fact:
Asynchronous remote collaboration is hard.
COVID-19 made it urgent.
Better writing is a solution.
Slack simply doesn’t cut it. If it will matter after today, stop talking about it in a chat room. Write it down, write it well, once and for all. Long form writing is the highest leverage activity.
So, if you were in the why-should-I-care camp at the top of this: get over yourself! Good writing matters. For your product, organization and career. Get with the program already!
The Pain
Last year I had to deploy an application to a platform that I had never used before. As I gathered information from the platform team I quickly realized: Documentation is not their strong suit. For example, I needed to configure network ingress for my application, when I asked them “How can I do this on your platform?” I got this:
Well, almost this (I can’t show you the real thing, because… secrets. So this is inspired by the real thing, but made up. All names are from lorem gibson, all numbers are random). That was the straw that broke the camel’s back, the camel fell off a cliff, unleashed an avalanche of white rage over my being, I burst into a flames of pure, black rage and burnt everything to the ground. I wish.
After I regained my composure I thought about how to protect other developers from these anger-attacks. I decided to make developers at Rakuten better writers, so that their readers will…
…quickly understand: Is this mean for me? Does this answer my questions?
…be able to navigate & understand content with ease.
…get the right level of detail to accomplish their goals.
The result of this effort is a half-day training in technical writing, split into 10 mini-lessons.
Preparation
“Give me six hours to chop down a tree and
I will spend the first four sharpening the axe.”
― Abraham Lincoln
The first 5 mini-lessons are all about preparing for success. Many factors determine how useful your documentation is, a lot of them happen before writing!
#1 Determine Target Audience
💡 Define a target audience and what they will learn from your document.
When I'm writing, I try to visualize my audience first. Who am I writing for? What problems are they trying to solve? A clear understanding of who I'm trying to help focuses my writing on what matters. That way I can easily decide what to include and what do omit.
For example, a team developing an Android SDK will write a document targeting Android App developers. That document focuses on what the app developer needs to know and the problems she might run into. It excludes concerns, questions and problems of product managers, operations, engineering managers, accounting etc.
It’s like separation of concerns, just for writing… words instead of code.
#2 Put it in Context
💡 Position your documents relative to the overall system.
Your system doesn't live in isolation. Put it into context. There are several contexts your system may live in that are relevant to your readers:
Your system is part of a bigger system.
Your system has different target users.
Your system is used by different stakeholders.
Your system may have competitors.
Your system may be geographically restricted.
For example Geocod.io is a wonderful geocoding & reverse geocoding service. But it only works for the US and Canada. European readers want to know that as soon as possible, before wasting time on reading all the docs. Geocod.io does a great job at clarifying this in the very first sentence on their landing page.
Being clear about the context of your system up front is key for your readers, so they can decide to stay or leave.
#3 Be formal, if you must
💡 Write as formal as necessary and not a bit more.
Formality is a bitch. Highly formal documents are hard to misunderstand. But also hard to understand. So we only use very formal writing when absolutely necessary.
Contracts between your software and other software must be highly formal. That includes web service interfaces (what many people think of when they hear the acronym "API"). That also includes library interfaces (functions, classes, objects), remote procedure calls, inter-process-communication or any other integration point into your software / system.
Another type of document that needs to be formal is technical design documents. Often those are read by technical product managers, developers of the solution and sometimes project & people managers. Everyone comes to it with a different mindset and background. Therefore I often define a shared language for such documents. RFC 2119 is a great starting point for that. It defines clear vocabulary for stuff that is required, allowed and forbidden. Like keywords in a programming language. Such well-defined & shared language is particularly useful when many readers are not native English speakers.
Formality is a tool we use to communicate clearly. Like every tool it's good in some situations and shitty in others. Use it carefully.
#4 Chose the right Medium
💡 Chose a medium/tool appropriate to the content, audience and formality.
At this point we know (1) our target audiences (2) their sets of problems and (3) the right level formality. We've done all the right up front work, we came with the best intentions...
...but it can still go wrong if we chose the wrong medium.
I have a wonderful example for this, a developer guide. In a 50 page word document. 🤦♀️
Without navigation. With code snippets, but no syntax highlighting. With code snippets in screenshots, so forget about copy paste. With code and regular text interleaved, forget about copy paste again. And with code overflowing to the next page, forget about copy paste already…?! The guide makes it so hard to follow its instructions correctly, it’s comical. I’d love to show you, but… secrets 🤷♀️.
So what is the right medium? Here’s suggestions some suggestions:
Library integration guide for technical audience → Markdown, or a wiki
Java library class level documentation for developers → JavaDoc
Product integration guide for product & project managers → Wiki, slides
Web service interface contract for developers → Open API Spec (rendered)
Solution proposal for business unit stakeholders? slides, Word, PDF
And here’s a couple of “please don’t do this 🙅♀️”
Technical Integration Guide 🙅♀️ Word, PDF, Confluence, Excel, PowerPoint
Code level documentation 🙅♀️ Word, PDF, Confluence, Excel, PowerPoint
Web Service Interface 🙅♀️ Word, PDF, Confluence, Excel, PowerPoint
Technical Design Document 🙅♀️ Word, Excel, PowerPoint
Product Overview 🙅♀️ UML diagrams
The content-medium mismatch is one of those things that you can’t unsee. Once you notice it… it starts to annoy the shit out of you. Content-medium mismatch is particularly prevalent in proprietary software documentation, in my experience. So please, please, pretty please with a cherry on top: Pick a medium that suits your content before you pour hours and hours into writing documentation.
#5 Version the document if necessary
💡 Version all documents that serve as a technical contract.
Contracts between your software and other software must be highly formal (see #3). Versioning is a related topic, as a rule of thumb all contracts also need versioning. Versioning enables you to change your system without impacting its users. Versioning is critical for business continuity. (BCP goes beyond the technical documentation of the system. We'll focus on documents for now. )
Versioning means change logs. Versioning means a versioning scheme.
There are standard versioning schemes for webservices and libraries. By following these versioning schemes you effectively communicate breaking changes to your users. They won’t accidentally upgrade to a newer version that breaks their app and complain to you about it (at least not as often…).
Wrap Up
That’s it! Use these 5 mini-lessons to prepare yourself and your writing for successful documentation. I’ll cover the second half, the 5 mini-lessons about the actual activity of writing, in a future edition of the newsletter. And before you go, take a copy of the Tech Writing Cheat Sheet, a concise summary of the 10 mini-lessons. Next time you write some docs open the cheat sheet and write like a young god. 🤘
Hyperlinks
Work to Publish
A great narrative reminder that as creators we strife for perfection. But at some point we just have to stop and publish our work. While he speaks about artists the same is true for writers and programmers. Some get dragged down perfectionism, they don’t deliver (“just gotta fix this one little thing”) and they are perpetually unhappy. So don’t work to perfect, work to publish!
What architects are not
Sometimes, it’s easier to describe what something isn’t rather than trying to come up with an exact definition of what it is. In the case of architects, exaggerated expectations [..] lead to a scenarios in which architects are pulled into several roles that clearly miss the purpose of being an architect
Gregor Hohpe on point, as always. Clear thought and simple writing 🙏..
Beware Engineering Media
How hacker news, tech twitter, conferences etc. trick developers into making bad tech choices. (Just recently I stumbled into a system that uses kafka internally for no discernible reason.) They compare engineering media to a bazar:
Picture a gargantuan bazaar in ancient times. [..]
First, the merchants in the bazaar are there to convince you of one thing: to buy their product. [..] In the bazaar, the merchants set the tone. [..]
Second, the bazaar attracts buyers of all stripes. [..]
Third, the owner runs the bazaar with an eye to maximizing sales, mercilessly favoring the merchants that are successful. [..] Beyond misinforming us, this drive for engagement manipulates our desire to not get left behind. To stay relevant, it seems that we have to use the technologies most hotly discussed.
It can be hard to choose boring technology in the face of an overpowering onslaught of fomo-tech-media.
That’s it. If you enjoyed this ☝️ subscribe or share it with a friend.