A tech writer's letter to software developers
Dear software developer,
You might have heard about technical writers, those mythical creatures. You might even be working with one. Whatever the case, I’d like to send you advice on how to achieve a healthy work relationship with technical writers so that you can get the best possible documentation for your product.
1. Advocate for technical writers at your workplace
You’re a developer, so of course you value technical documentation, as the Stack Overflow Developer Survey shows. Documentation, though, has the nasty habit of not writing itself. Even if you’re fond of penning docs for your features, you’ll find that getting them beyond the bare essentials requires tons of time. That’s why you need specialists who’re able to understand what you’re doing and craft docs on it. They’re called technical writers. Ask your manager to hire at least a couple, you won’t regret it.
2. Embed a technical writer to your team
You’ve hired a tech writer? Brilliant! Now it’s time to get to know each other. The first and best step you can take is to invite the writer to your team channels and add them to your team meetings and ceremonies (except the one where you sacrifice a silicon wafer to the gods; not that one). Welcome writers to your world and include them in conversations: They’ll adapt in no time. If you treat writers well, you’ll find them to be generally friendly, humorous, and supportive of your work. We’re nice people, really.
3. Be yourself around tech writers
We might not look technical enough to you, but that’s no reason for you to behave differently. Our task is to obtain product truth by asking you questions and observing your everyday activities while taking notes. We tech writers are a bit like cultural anthropologists in that we don’t want to alter the status quo. Quite on the contrary, we want you to talk as you’d be talking to people in other technical roles. If we don’t understand something, we’ll let you know. If we need help, we’ll ask for it.
4. Don’t feel bad about your writing skills
You might feel bad about your writing prowess. We know, we read all those threads on Hacker News on how to improve as a writer. Don’t worry about it, though: We don’t come armed with red pencils, ready to strike errors in your drafts and put you to shame. Writing is hard for everyone, including technical writers. You can become a better writer simply by asking us for feedback. If we can teach you some stuff, it’s not because we’re smarter: It’s just because we’ve been doing this for longer.
5. Include the docs in your Definition of Done
Your product won’t exist if you don’t document it. It doesn’t matter if it’s an internal tool for a small group of build engineers or a massive feature with impressive design: Without docs, it won’t be ready to take over the world. Work with your engineering manager, scrum master, and product owner to include documentation in the Definition of Done or in the Acceptance Criteria. Make room in your epics for docs tickets. Include the documentation in your demos and writers in your credits.
6. Provide Minimum Nuggets of Knowledge (MNK)
We tech writers are able to document a feature almost on our own by reading your source code, tickets in the issue tracker, and casual Slack messages. At some point, though, we’re guaranteed to hit a wall, because we need what’s in your mind. So, go ahead and dump your brain into Markdown files, or fill out a Confluence page with how the thing is supposed to run. You can even use code comments. As long as you’ve left a written trail of evidence about your work, we’ll be able to grow docs out of it.
7. Teach us how to do the magic you’re doing
Spend some time working with us and you’ll find that we’re not only unafraid of technology, but also quite willing to run processes on our own and test the software ourselves, to the point that we’d do some testing on your behalf. Like you, we tech writers wrestle every day with fragile toolchains, trying to push docs out in the world while fixing bugs and coming up with workarounds. We want to see the bugs, get a feeling of the release process, and count the Time to Hello World on our machines.
8. Review our drafts when you’ve a moment
In exchange for processing your knowledge, we only ask for one thing: Review the drafts we send to you so that you can tell the good bits from the ones that smell bad. We might have reached a good enough approximation of your work or be completely off track, but the docs won’t be finished until you tell us “ship it”. And if you can’t review the draft for some reason, let us know. We’re a patient bunch, though it’s better when we know why we’ve to wait. We can empathize. You won’t look bad and we’ll still like you.
Gratefully,
A tech writer