Set your project up for success with a documentation brief

The documentation brief is my secret weapon for delivering a document that meets the readers’ needs.

Technical writers set their documentation project up for success when they invest fifteen minutes to an hour understanding the documentation goals, securing resources, and setting realistic expectations before they start planning. In this post, I explain what the documentation brief is, and how it achieves these goals.

What is the documentation brief

The documentation brief compares to the project charter in the Project Management Institute’s PMBOK^® Guide, tailored to documentation projects. The project charter “formally authorizes the existence of a project and provides the project manager with the authority to apply organizational resources to project activities. It documents the high-level information on the project and the product, service, or result the project is intended to satisfy […].” [PMBOK 2017, p. 81].

Similarly, the documentation brief confirms:

That this documentation project is a priority.
That the sponsor will assign resources (employees, tools, and license costs) to its execution.
What need the documentation fills.
How we will measure success.

The reason why I never call it a project charter is that my co-workers are way keener on meeting me for a documentation brief; or even better a “hey, I’d like to sit with you fifteen minutes to discuss your documentation request.“

Why is the documentation brief important

Start on the right track

The documentation brief helps the writer understand the documentation goals from the onset of the project, and consequently reduces the need for major edits in the long run.

I recently received a request to write standards on how developers should document in my organization. Without a documentation brief, I would have prepared a mini-series of presentations on how to use UML to document software. During the documentation brief, I found out that what the project manager wanted was an informal policy on how managers expect developers to document their code: what to document, and where.

Recognize the subject matter experts’ effort

Most of the documentation I write involves interviewing Subject Matter Experts (SMEs) and requesting their reviews. This effort takes time away from their normal duties. Therefore, their project manager needs to account for the time spent on the documentation project in their workload.

When to work on the documentation brief

You should start working on the documentation brief as soon as you know you are going to work on a new documentation project.

I loosely follow the scrum methodology, and use Jira to plan my work; if you are not familiar with scrum, I encourage you to read the scrum reference card. The timing and philosophy of the documentation brief is very close to story grooming. I start working on the documentation brief as soon as a documentation task is added to my short-term task list. At the latest, the documentation brief should be complete by the time I add the corresponding task to my next sprint’s backlog.

How to prepare the documentation brief

I have found that the most effective way to get the documentation brief done is to:

Sit down with the person who requested the new documentation (I’ll call them the reporter from now on, because this person reported the need, and that’s how Jira calls them) for an informal chat of about fifteen minutes.
Extract from the reporter’s brain the information asked in the template I discuss later in this post.
- Instead of using the template as a script, I let the conversation flow as freely as possible.
- I let the reporter lead as much as possible.
- But the template is here to remind me of the answers I need to get.
Follow up on missing information with the reporter or other stakeholders.
Write down the project documentation brief.
- Because I use Jira at work, I write it in the description field of a Jira issue, but any format will do.

What to include in a documentation brief

Downloadable documentation brief template

I have captured the information that I collect during a documentation brief in a Google Document that you are more than welcome to re-purpose for your needs.

Click here to view the documentation brief template in Google Documents.

In the paragraphs below, I detail what I expect in each section of the template.

Elicit the documentation requirements

Objective and background

The first answer that the technical writer needs is: why do we need this documentation; what need does it meet, and how what we have does not meet this need.

It’s always good to ask the reporter what problem they are trying to fix with new documentation:

Do they want to document a process for training purposes?
- Is this a new process, or just a process that was never documented before?
Did they notice discrepancies in how employees interpret their roles and responsibilities, and want to clarify that?
Is there an aspect of the software implementation that is so tricky that new developers spend days understanding the code before they can work on it, and the documentation will help them ramp up more quickly?

It’s also insightful to ask the reporter at what step in their current process they will use the new documentation.

Target audience

Knowing whom you write for shapes what you include in the documentation, how you write it, and how you distribute it. For instance, I never expect a customer success manager to go to GitHub for information on how our product works. However, developers appreciate finding a readme on how to set up their environment directly in the GitHub repository.

Documentation goals

The documentation goals are different from the objective and background in the sense that goals are measurable and somewhat objective (not always easy when we talk about documentation).

In an agile world, documentation goals are the acceptance criteria for your product.

Examples of documentation goals include:

Give your readers the information they need to make a decision.
Reduce new hires’ ramp-up time.
Help your organization pass their next audit with documented processes.

Scope

Reporters often have a good idea of what they want; it’s also good to define boundaries and understand if there are things that we don’t need: maybe they are already documented elsewhere, maybe the readers already know them, or maybe we know it’s going to take too long to deliver, so we’ll get to that later.

Publication type and medium

The type of documentation that you write and the medium that you publish it on impact how you present and organize your ideas. As a result, you want to know this information early in the writing process.

Types of documents include:

policy,
API documentation,
integration guide,
requirements,
proposal.

Types of media include:

a PDF file that your manager will attach to an email,
an article in your company’s internal knowledge database,
a login-protected documentation website,
your company’s public website.

Secure your support team and resources

If you’ve made it so far in the document brief, you have a good understanding of what you will write. Now, you have to secure the resources that will help you deliver.

Subject matter experts

The subject matter experts are the employees who have the most knowledge on the topic you are documenting.

You always want your sponsor’s blessing on whom you are allowed to interview for your documentation project. The time and effort that they spend working with you needs to be accounted for in their workload and recognized.

Sometimes, you cannot work with the best SME for the job, because they are assigned to high-priority projects. When that happens, your options are to either review your timeline or add this as a constraint to your documentation brief.

Resources

It’s always a good idea to ask the reporter if they have examples of documentation in mind that look like what they want and examples of what they do not want. I always ask the reporter if they are aware of existing documentation that I can reuse for my project. I can and should find that out on my own, but hey, if I can get this information for free by just asking, why not?

Documentation owner

The documentation owner is the employee who has the authority to sign off that the documentation is useful and benefits its intended audience. They have an interest in disseminating the documentation and ensuring that it remains up to date.

The documentation owner is often the reporter, but not always. His role in my documentation brief is inspired by the Six Sigma’s process owner.

Documentation sponsor

The sponsor is the manager who has the authority to assert that the documentation project is a priority, and to assign resources to it.

You need to know who your sponsor is: that’s the person you will ask resources from, and the person who can help you when you bump into difficulties.

Find out what constraints you are working with

This section is useful in setting realistic expectations with your stakeholders. You want to document any factor you know of that will limit what you can deliver in the time and with the resources that you have.

Requested timeline

Always ask the reporter if you are working against a hard deadline.

If there is no hard deadline, document by when the reporter wishes the documentation delivered, and why.

The requested timeline is not always achievable. If you don’t think you can meet your deadline, you need to communicate that to the reporter.

Assumptions

Assumptions are factors that are important for the success of your documentation project, and that you are reasonably confident you’ll get.

If an assumption turns out to be invalid, it’s a red flag that you should get back to your sponsor and ask for their help. Examples of assumptions for a documentation project include:

availability of the SMEs,
quality and timeliness of their reviews,
access to the software you have to document,
access to the source code you have to document.

Dependencies

You may depend on the completion of other work before you can finalize your documentation. For instance, if you have been tasked with documenting a new piece of software, it needs to be testable before you start working on it.

List all known dependencies, and keep track of them. If you see a dependency starting to slip, this will impact your timeline, and you have to inform your stakeholders.

Other constraints

List any constraints that you are aware of, that weren’t previously listed. Examples of other constraints include:

An SME leaving the company,
Reduced SME availability,
Sensitive information that you should not include in the documentation,
Tools that your organization forces you to use — or prohibits you from using.

Access restrictions

It’s important to know if your company restricts who is allowed to read or edit the documentation that you produce. Access restrictions determine how you can store and share your drafts, whom you can ask for reviews, and where to publish the final product.

Restriction access is typically one of the following:

Only a subset of the employees at your company,
Internal (all employees at your company),
Confidential (all employees, and vendors and partners who have signed a non-disclosure agreement),
Public.

Wow, that’s a lot; do you really get all that info in less than an hour?

I rarely ask all the questions listed in my documentation brief template, because that would stretch the reporter’s attention. I start with the most critical sections:

Objective and background
Target audience
Documentation goals
Requested Timeline
SMEs
Resources
Sponsor

If I already know the answer to a question, I merely ask for the reporter’s confirmation.

When the person I’m meeting with starts losing interest, I call it quits. I follow up later if I absolutely need a missing piece of information.

I have a documentation brief… now what?

Once I know what I’m going to deliver, and who my support team is, time to schedule appointments with the SMEs!

References

[PMBOK 2017]

. (2017) A Guide to the Project Management Body of Knowledge (PMBOK^® Guide). Retrieved from https://www.pmi.org/pmbok-guide-standards/foundational/pmbok.

[Scrum Reference Card]

Michael James and Luke Walter (2010). Scrum Reference Card. Retrieved from https://www.collab.net/sites/default/files/uploads/CollabNet_scrumreferencecard.pdf