Search results

Doc Plan Pains and Empowerment

by Tom Johnson on Dec 3, 2010
categories: technical-writing

One part I enjoyed about my Xtranormal videos was writing the script about the insane spreadsheet that the project manager foists on the technical writer in an effort to track, manage, and contain the writer with busy work. That's how PM templates have always seemed to me, which explains my reaction when Derek, my colleague, told me he was creating a user education template for a new project management methodology -- I wasn't excited about it. I reviewed it cursorily, nodding in agreement because I really didn't want to spend much effort with the thing. Looks great, nice work.

I know I like to complain about how technical writers are left out of the picture. Not invited to meetings with users, not adequately informed about projects ahead of time, not invited to the prototype design reviews, not given access to the right environments, and so on.

All this is legitimate, but lately the trend has been swinging the opposite way. Project managers are asking me for help content -- early. They're inviting me to too many meetings. They're extending a welcome hand into their projects, to review prototypes, to be an influential voice.

Problem is, there's not enough of me or time to do it all. I thought I could extend my efforts through community-empowered volunteers that I could direct, but that didn't work out so well. I added project after project on my plate. I have a hard time saying no. Oh, you need some help for an upcoming project? When are you releasing it? Not for 3 months? I can work with that. I can get you the help you need.

I had this same conversation with a handful of project managers, agreed to create help for this and that. Deadlines were too far off to be too concerning. I had billing codes and plenty to do. I had done help for these PMs in the past; why could I not repeat the performance now?

If that wasn't enough, I started looking for ways to exert some influence in information gaps I perceived in our organization. I read user forums, wrote articles to fill gaps, got involved in even more projects. It doesn't take much to find a new project. Start interviewing someone about a new app they're working on, and the inevitable question pops up -- what's your help solution for this application? Oh, we really haven't thought about that yet. I can help ...

Not only do I have a bad habit of saying yes to everything, I also prefer to work outside of strictly defined timeframes and schedules. Give me a release date, tell me what you need, and I'll create it. That's my style. But this style starts to implode on itself because every time I see one of the project managers, they want to know the status of the help. And the scope seems to increase. I find myself logging bugs, getting involved in prototype designs, sitting in scrums, triaging issues, deciding on key features, helping customers -- in short, becoming the key player that I argued heavily for in my series From Overlooked to Center Stage.

The help doesn't get written because my time is spread so thin. Right now I'm booked out until at least mid-next year. In a recent team meeting where we meet to discuss standards, I found myself without energy for the discussion about "teeth" and early integration into the software development process. Integration? I don't need earlier integration. PM's are integrating me -- we just need more resources. Can we hire another technical writer? Can I hire an intern? It turns out Derek had brought up the same question with our former manager the previous week.

At this moment, I started to see the value of this user education planning template Derek was creating. Although I like to do work on an informal agreement and handshake, I realized this method would soon bury me into an inescapable sea of work. Unless I could define the exact work required and the time it would take, I would take on too many projects and end up incapable of delivering the quality of work I want to create. Unless I better defined the scope of the work, the expectations, and the deliverables at the start of the project, I wouldn't be able to complete the mass of work that I was agreeing to do.

Derek's 23 page user education planning template hits all of the major components of a documentation plan: objectives, audience, risks and dependencies, localization, SME contacts, milestones, content models, approvals, assumptions, budget, scope, content outlines, strategy, tracking, and more. It's a document that forces you to think before leaping and agreeing to unreasonable timelines. It's a document that helps get the project manager on the same page as the technical writer in terms of expectations and realities.

I admit, embarrassingly, that I haven't completed an official looking user education plan of this scope for years. But I am starting to realize this has been a serious mistake. If I plan to keep my sanity and do a good job with help content, I'll need to more carefully anticipate the work and requirements for the projects I take on. It's better to do a good job with help content on a few projects than a scattered, half-effort on a large handful of projects. In the end, rather than a brick that drags you down, the doc plan is like a life-saver buoy that keeps you from drowning.

A documentation plan can save you from drowning in a sea of unreasonable scope and timeframes
A documentation plan can save you from drowning in a sea of unreasonable project requirements and time frames.

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.