9 Questions for Setting Expectations on Your Documentation Project

9 Questions to Help Set Expectations for Your Documentation Project (1).png

Ever do a ton of work only to realize that you and your boss weren't on the same page? It's possibly the worst feeling you can have at work: that you put time and effort into something that isn't even what the boss wanted, or thought they'd asked for. Technical writing is fraught with opportunities for these little miscommunications that lead to wasted effort, wasted time, and drained motivation.

Part of the solution is setting your documentation scope clearly and early. But defining scope is't the whole answer. You understand what you need to do to write the docs, but do your team members understand what they need to do to support your work? Ask these 7 questions at the beginning of the project to get everyone on the same page.

What are my deliverables?

This is a scope question, to be sure, but not one to miss while setting expectations! Although it can feel obvious when a project manager asks you to "write something up" for a client, your assumption could be exceedingly different from theirs. I have a weakness for writing user guides (I like long-form, what can I say?), but I've found that managers are typically looking for something short and punchy like a quick reference, or that they want the quick reference first and a detailed user guide afterwards. Make sure you understand what they want, and whether there's more than one deliverable involved.

Who are my SMEs, and how will we transfer knowledge?

The Catch-22 of writing docs is that you often know little or nothing about the product, but it's your job to teach others about. To resolve the Catch-22, you need the knowledge encapsulated in your SMEs. Unfortunately, they can be hard to pin down, especially when they don't know who you are or why you need them. Make sure you know the names and contact info for your SMEs (especially if you don't work in the same location) as well as how you'll meet up to learn about the product, and how often. Especially if you're in different locations, it can be helpful to get an introduction from a manager so the SME's phishing sensors don't go off as soon as you ask a question. If possible, also try to get names and contact info for other people who can help if an SME goes on vacation.

What's the schedule?

This seems like an obvious question on the surface, but it leads to a much more difficult question: what is the documentation schedule? For example, a PM asks you to write a quick reference and tells you it's due in a week. What does this mean? Should the first draft be done in a week so it can go to its first round of reviews the following week? Should it be completely written, reviewed, and ready to go to the client in a week? These are drastically different schedules. Even managers who've worked with writers before can forget how long it takes to get even a short doc out the door. Make sure you confirm the schedule before you start writing.

How should I update the team about my progress?

Some teams are very hands-on and want updates constantly; others are happy to leave you alone for a month to write uninterrupted. Not only is it important to know whether leaving them in the dark for a whole week (!) will lead to the arrival of search parties and cadaver dogs, but it's also important important to know how much of your workday/week/month will go into providing updates instead of creating docs. While you're at it, figure out who should be included in updates and how detailed the updates should be.

What is the priority for documenting each topic?

You may be a magical writing unicorn and can get topics off your desk at inhuman speeds, but you cannot produce all topics simultaneously. This means you have to choose what to write first. But what's most important? The most complex topics? The most commonly used topics, even if the subject matter is intuitive? I'm sure you already have a strong opinion about this, so I'm not going to try to sway you. But you should understand the priority that project management has, and come to an agreement with them on the right order to complete your work.

How will I get updates from development?

The dream of every technical writer: to have a static target toward which to write. The reality: a moving target. Because you'll often write about something that doesn't even have a UI yet, it's important to know how you'll find out about changes to the projected UI. Heck, even if there is a UI, who do you know it hasn't been changed without your knowledge? Ask whether you can be part of scrum meetings, have access to user stories, or if it would be better to set a weekly meeting with a Business Analyst or Project Manager to sort this stuff out. And if they can't give you access to any of that, make sure they know they'll pay for it in several weeks of docs QA and rewrites once the final product is out the door.

Who should I talk to if I need to escalate?

The best laid plans of mice and men get fucked up when an SME just. won't. answer. If you have a manager you can talk to, that's a start. But sometimes that manager is the problem, and sometimes you are the manager. Get the names of at least three people who can help you move the glacier. A basic understanding of the org chart doesn't hurt, but if there are specific people who want to be involved in unplugging a bottleneck, find out their names (and throw a parade for them through the middle of town).

How will we conduct reviews, and who needs to be involved?

This one is tricky enough that I plan to address it in a separate post. But briefly: figure out everything you can about reviews before you write a word of docs. You want to figure out when to send docs, who to send them to, and what you expect to get back. Does your team want to review the docs little by little as you write, or all at once when the docs are done? Do they think no response to a review email means "good to go"? (It doesn't mean that, no matter what they say.) What constitutes helpful review comments? How fast do review team members need to respond before you move on without them? Should there be both an internal and external review, and what do those terms mean to your team? How many rounds of reviews will there be? Who wants to be in the To field for the review email, and who wants to be in CC? Get all this down and send an email with the info to everyone involved so there's no doubt about responsibilities and expectations.