Search results

Balancing the never-ending list of documentation to write with your natural interests and passions

by Tom Johnson on Sep 2, 2016
categories: technical-writing podcasts

Sometimes I think that I've covered every possible topic on this blog that is possible to write about, and my muse becomes silent for a while. But then I remember the purpose of the blog -- to be a web-based log, or journal -- and I realize that the only reason I wouldn't have anything to write about is if I stopped having experiences, stopped reflecting on those experiences, and ultimately became a zombie. That zombie state is the death of any career.

Listen here:

Although most days are the same, they are a little different. My kids have returned to school, and so my summer routine of waking up “when I wake up” and riding my 8 miles to work along the scenic San Tomas Aquinas trail (which follows a half-dry canal) has changed a bit. I now ride my kids to school and then ride on to work. My two youngest (6 and 9) often glide along on roller skates while holding onto the back of a bike child carrier that I pull. My older two kids get themselves to school by bike and foot.

My wife is an early riser who leaves while it’s still dark and heads up to the “Dish” in Palo Alto to walk along a trail that is so popular, if you don’t get there before 7am, there is not a single place to park for what seems like miles.

The extra ride to school adds another 4 miles to my route, which puts my daily biking round trip at about 20 miles. When I also add in a few games of some post-work basketball, all the exercise can seriously wear me out. (Unfortunately, I still manage to eat enough calories to more than enough compensate for all the calories I’m burning.)

The fatigue from riding sometimes carries over into a sense of fatigue about endless documentation tasks. I’m still trying to follow Tim Ferris’ advice to focus on the highest two priority items first thing in the day and block out everything else.

Sadly, I’m lucky if I get one of the two items finished. Even if I do finish it, I usually can’t publish the documentation I write until I can get the right subject matter expert to review and sign off on the content – a process that can take anywhere from a few days to more than a week.

It would be more encouraging if I could see the to-do items decreasing little by little, but I think the reverse trend is happening. For every item I knock off my list, two more get added (both for tasks at work and at home). Sometimes I feel like I’m slowly sinking, and as much as I try to conquer the documentation mountain, it just keeps rising higher and higher in the sky.

I dream about a day when I’ll have marked every task as “Resolved,” like having reached a state of Inbox Zero. In this state, I’ll tackle incoming items with such a responsive velocity that those who requested the update would be surprised at how quickly I turned it around, like when you find that someone has responded to your email just seconds after you sent it.

It crossed my mind today that perhaps instead of writing documentation myself, the only way to truly scale and conquer this documentation mountain is to switch from author to curator. A marketer who works near me noted with glee how she already has four posts she is publishing on the company blog this week. Did you write them all yourself? I asked, ready to be impressed. No, she said, teams reached out to me with the content.

I’m not sure I would be entirely satisfied being a content curator instead of an author. Writing is my sweet spot, and where I perform my best (except for maybe setting up authoring tools). But no doubt a hybrid role of author/curator is essential to survive.

While the documentation tasks keep building, I’m also trying to build up my technical knowledge of Android and the products I write about. There’s a lot to building streaming media apps – it isn’t something one learns in a few weeks. What’s more, the developer audience is at such a higher technical level than I’m at, my documentation has to hit on the questions and gaps of knowledge they will run into, not just me. I just finished editing a document about 4K Ultra HD media that has so many details about refresh rates, color formats, codecs, and other specifications that I wonder if I’ll ever get to the point where I can consume this information as easy as reading a morning newspaper.

I try to get into work a bit early to push through some tech tutorials in the morning and at lunch, but taking time out of my mounting doc tasks to step through a tutorial is always a trade-off. Am I sharpening my ax, which will make it easier to chop down the tree? Or am I learning about something so disconnected to what I’m documenting that by the time the material becomes relevant, I will have already have forgotten it?

That’s the crux of ramping up on developer technologies – unless you’re immersed fully in the domain for an extended period of time, the info doesn’t entirely stick, and it slowly fades. Then months later you have a documentation task that requires the knowledge, but by then it’s only a dim memory.

One day I’ll be an Android master, and I’ll know these products inside and out. I’ll resolve all of my JIRA items, and I’ll find myself wandering up and down cubicle aisles chatting leisurely with colleagues because I literally have nothing to do since everything is done.

But that day is a long ways into the future, and I only have a vague idea of how it will be. It’s mostly a dream. I know that the longer I’m at a company, the more projects I work on, the more documentation I’ll become responsible for, and the less time I’ll have. If any bandwidth opens up, more projects will take hold of that bandwidth until it is maxed out. Maybe someday I’ll even have a “direct report,” which would require even more bandwidth.

Maybe it’s not the tech writer’s destiny to ever get a perfect handle on all the open doc tasks and master all the technology details. Maybe this state of slowly sinking but then somehow pulling myself up a bit each day is the permanent state of technical writing. Is this what makes the job interesting – the challenge, the steep learning, struggling against the insurmountable?

I reflected on this idea during several of my bike rides to work, in between listening to books on Audible. I’m currently listening to Ready Player One, by Ernest Cline. In the book, a brilliant video game designer (James Halliday) creates a virtual reality layer to every day life that becomes a new dimension that most of humanity interacts in. The earth has deteriorated, poverty has increased, and the only alternative to the dismal, gray, degenerate life on earth is the virtual world Halliday created, which he called the OASIS. (The book is set about 30 years into the future.)

In the OASIS, students attend school, interact with each other, and do pretty much everything that you would expect in a normal world – except that they do it by sitting in one spot wearing OASIS goggles, moving their haptic gloves (or haptic suits for those who have more money), and by manipulating their avatars. Their avatars can complete quests, collect magical items (which they put into their “inventories”), teleport from one location to another, explore different worlds, and so on. It’s a pretty engaging book with detailed and believable world-building.

One day the OASIS developer, Halliday, dies. He is enormously rich and with no heir. Who will he give the money to? He decides to create the ultimate game and award the prize to the first person who can find the hidden easter egg. This sets off a ton of adventures with our main protagonist, Wade, who learns everything he can about Halliday’s world – the video games he played, movies he watched, and other 1980s trivia from Halliday’s youth.

I’m only half way through the book, but I’m guessing that eventually Wade will win this game (or else team up with his cybercrush Ardemis and win it). But that’s sort of beside the point.

What is my point? Both Halliday, the brilliant video game creator, and Wade, the game-playing protagonist absorbed in Halliday’s video game and world lore, love what they do. Wade is engrossed in Hallidsay’s 80’s pop culture, video games, and life in the OASIS. It pulls him in fully and absorbs all of his attention. He loves video games and plays for the sake of the game.

Let me circle back to the mountain of documentation and other tasks. On the one hand, I could view this as a kind of endless list of to-do’s, the only really interesting thing being checking off the boxes beside the tasks. I’m not sure I can ever fully change my attitude to embrace the same zeal and drive that Halliday and Wade have with video games, but I am convinced that this element of fun, of obsession and interest and full absorption, is what drives one toward total mastery and ultimately brilliant feats of accomplishment.

The problem is that one’s natural inclination doesn’t always align with profitable outcomes. For example, Wade’s mastery of 1980s video games and life in the OASIS doesn’t do much for him financially except qualify him to work as a tech support agent at a company called Helpful Help Desk.

This past week I sort of let go of my goals and tried to get absorbed in my natural interests. You know what I ended up doing? Jekyll stuff. I refactored the Jekyll doc theme at my work to support translation, figured out how to drive a glossary and tooltips from a YAML file (across multiple languages), came up with a nifty technique for handling bookmark links from the sidebar navigation, integrated Bootstrap nav tabs into the UI, explored how other theme developers implemented breadrumbs, interacted a bit on the Jekyll talk forum about templates, and more.

If I wanted to put my mind to it, I could become more adept and skillful in creating documentation themes out of Jekyll. But as my wife reminds me, when you compare building this kind of knowledge against knowledge about Java, Android, or other programming languages, there’s a clear winner about which one has greater payoff. And that’s the dilemma for me. It is easy to get wrapped up a publishing tool, but developing content about technical issues developers face is the real payoff from a career standpoint. One day you could change jobs to a company that uses a different approach for authoring, and then all that tool knowledge would be wasted (most likely in the same way that learning Android would be irrelevant if you suddenly joined Apple).

I’m still in flux. I can develop a mediocre knowledge of developer tech, or I can go deeper with Jekyll, or maybe explore something else altogether, like web publishing in general. The web (not too unlike the OASIS) is the larger funnel for most of my activities. Regardless of the direction, all my activities seem to converge in building out my technical skills, which no doubt helps in any technical writing endeavor.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.