One time, I said to some people “I could be your technical writer” and they said “okay.” And then I was a technical writer.
Everybody looked around for a bit and then went back to their computers, so I started doing things.
I read a book and some blog posts and I was ready for action!
The assignments were going to arrive well-described, one at a time. I would instantly understand what was needed, then lovingly craft exactly the right words in exactly the right amount of time and feed them into some kind of machine so they’d show up right next to new releases.
But that didn’t happen. You figured that out.
I didn’t need to wait on anything because there were already lots of unwritten blurbs waiting on me to write them. Some blurbs had been written that were very old and needed to be updated. Others blurbs were up to date, but confusing or not where you might expect to find them. A few had screenshots that had been painted on cave walls. And this was all in documentation that was pretty good—I’d say above-average good—before I even arrived to survey the scene!
New features came along anyway! Sometimes I’d find out in the release notes and think “wow, somebody should have documented that.” Which was awkward because nobody else’s face said “technical writer” under it on the website. Just my face.
Fine. Write some of the missing blurbs, spruce up some old ones, get some of those new ones out the door just in time. When I understood the things well enough to write about them—and I should have since I spent a lot of my career working with the software—writing and publishing things wasn’t so bad. The docs were already there with a publishing workflow.
But sometimes I didn’t understand enough to form useful words. It could happen with old things and new ones. I might have missed the point and needed to spend time with issues or support tickets, or interview the person who made the thing. They might forget what they did, or we might find out together that the thing doesn’t work right, or that a clueless newcomer’s first instinct might send them tumbling headling into a path of suffering.
“Careful with those crusty old sentences,” no one in particular would say, “we arranged those just right after a long support thread once and you’re walking on an ancient battleground.” So I would be careful not to trim too much or move things too far from where someone might expect to find them.
As if there wasn’t anything to do, I’d sometimes think things like “it’d be nice if this worked better” or “automating this would save time” or “we should have a process for this” or “it’d be nice if all this felt more like the website and the web app.” So I worked on those things too. I got to know the generators and the pipelines and the frameworks that delivered the words to the internet. Sometimes I’d be working levers I already knew. Sometimes I’d be like a pastry chef trying to replace a transmission and hope nobody wondered what the guy with the big funny hat was doing under the car.
Sometimes other people whose faces weren’t even on our website had ideas too! The docs should be built in a different way, or did weird things with that one browser while on a train, or the very old blurb or very new blurb didn’t help at all or had typos in it. Those other people, even when their ideas were insufferable, they were the helpful ones that bothered to share their ideas and their feedback. They helped make the docs better even though nobody was even paying them to pretend to be a technical writer.
So what I’m telling you is that good documentation is hard.
Documenting my own work took effort, but the person who understood the problem and wrote the code to solve it and tasked with explaining it all lived in my head so asking questions was easy and timezones were never an issue.
Documenting someone else’s work took a lot more effort. Unless the work was very simple—and sometimes even then—I needed them to explain it at least somewhere in order to get a good grip on the thing. They also had to deal with my questions, poor dears. And I had to keep up with their release schedule, however consistent or inconsistent it was. I needed enough time to write, but not so much that the thing might still be squirming and changing as I tried to sketch it.
But when there was enough time for it, my questions and attempts to hold it wrong were sometimes useful. With enough time, the conversation could lead to ideas or improvements—occasionally even ones that eliminated the need to have documentation! You’re thinking that’s because I didn’t want to do my job, but actually my job was to make things easier to understand and sometimes an adjustment to the code might eliminate any need to check the user manual. And everyone would rather not have to consult the user manual.
If you’ve ever walked through a river in new shoes, you know what bridges are for.
Understanding things is navigating a landscape you’ve never been through. There may be mountains and valleys and forests and weird little islands constantly formed and reshaped by engineers and designers. People need to get to different places, and you don’t want them to have to machete their way through or tumble over a cliff so you build roads and bridges.
I’m doing a metaphor.
Documentation is a series of paths and bridges and warning signs. Sometimes maybe an air conditioned shuttle system. You might be reading this and know you’re handing out machetes and satellite phones. That’s okay, because you’re building a new little world and the roads and bridges take time.
People are different. You’ve noticed this. They’re at different points in their careers, with different skillsets and backgrounds. They think and learn differently. You have to imagine where they might go, see where they do go, and listen to where they’d like to go in order to build the roads and bridges in the right places.
When people start wandering through this little world, the person who carved out the land isn’t there to explain it. They can’t tell you how they expected you to walk through it, or if they’re going to bulldoze everything there tomorrow or leave it there forever. They can’t tell you if it’s sacred ground or a pile of garbage they’ll be cleaning up after they get the other thing done over in that other spot.
They built it knowing how it’s supposed to work, and you need to know how to use it. Those are not the same.
“We’ll just add some documentation for this” is the “we’ll fix it in post” of software development.
Hopefully some documentation is there to show you a way through. But hopefully not just a way through.
If it all works really well, you’ll have a hard time getting lost.
Building really well and documenting really well takes clarity, coordination, and intention beyond the person pretending to be a technical writer.
Doing all this well—and this will be a shock coming from the writing person—probably takes a commitment to writing.
Any clarity of purpose, any time spent writing, is worthwhile and it certainly helps encourage better documentation. Some companies know this and make it a defining aspect of their culture. (You know they’re deep in it when they write about how they write.) Whether it’s part of the culture or a weird idea, a technical writer probably needs to be prepared to champion this, because a lot of people hate writing and would rather be trapped in an elevator.
They’ll maybe let you take notes, though.
I don’t know exactly how to be a technical writer, and it’s okay if you don’t either. Just know that it’s hard and it’s important and you need to build those bridges because you walked over a lot of them to get where you are.