Ever do a ton of work only to realize that you and your boss or client weren't on the same page? It's frustrating to know that you put time and effort into something that doesn’t meet the the client’s needs or match what they 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 isn't the whole answer. In addition to scope, you need to be sure your team members understand what they need to do to support your work. Ask these 8 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 what a project manager wants when they ask you to "write something up,” your assumption could be quite different from theirs. I have a weakness for comprehensive user guides, but I've found that managers typically look for something short and punchy like a quick reference first with a detailed guide later. 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 subject matter experts, or 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 SMEs’ 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 week will prompt the arrival of search parties and cadaver dogs, 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, how detailed the updates should be, and what format they should be in (in person, email, etc.).
What’s 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 based on user needs.
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 that’s still being developed or, at best, debugged. 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, how do you know it hasn't been changed without your knowledge? If your team does Scrum, try to get on the team. This will give you access to user stories and daily standup meetings that will make it easier for you to track these changes in real time. Alternatively, if your team doesn’t do Agile , try 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 the team understands that they'll pay for the lack of access with 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 fall apart 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 them a parade).
How will we conduct reviews, and who needs to be involved?
This one is tricky enough that it has its own 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 for review, 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.
Want to learn more about docs in Agile? Check out my eBook, “The 12 Principles of Agile Documentation.” Learn how the original 12 Agile principles apply to documentation, how to change your thinking to accommodate documentation, and the benefits you can get from bringing the docs into the fold.
