Plan: Before You Start Writing...

Now that you have your documentation strategy in place, it’s time to start…

No, writing documentation does not start with writing. In product documentation (technical) writing, actual writing takes only 25-30% of the writer’s time.

Great documentation starts with a plan. This applies to new products, new features or policies, updates, deprecations, and for documentation tasks that are independent of the latest development (you just want to make it better).

In this article, we take a look at the first of the five documentation life cycle phases - planning, the first stage of implementing your documentation strategy. It’s one of the reasons why integrating your project management tool and your docs authoring environment matters.

What Is a Documentation Plan?

Let’s say your team is releasing a new product feature. Or you need to create a document for HR about the new pension contributions policy.

A documentation plan is your team’s way of agreeing on what needs to be documented, how it should be organized, and who’s taking care of what – during this development and later, for maintenance.

It doesn’t need to be a big, fancy document (unless you want it to be). This could start as a digital whiteboard and maybe end up as a page everyone can access. A great way to ‘document’ the tasks from the plan is an issue tracking tool, like Jira. A good plan keeps your content organized, your team aligned, and your future self very happy.

The What and Why

Imagine you’re a writer, you work with your engineering team, designer, product manager. A new feature is announced.

What do you do?

You can get a lot of answers on planning and grooming meetings. The better you understand the feature (or an internal policy, etc.), the easier the planning and writing process is going to be.

Scope of documentation

Obviously, you must determine which aspects of the feature need to be documented. Developers would love to document every technical detail. You and the product owner might have a different opinion as you tend to value what is actually important for the user.

That said, you may decide what part of the documentation will be public and which details will remain internal only.

Defining the scope will inevitably impact existing documentation – more often than not, some existing sections may need to be updated due to dependencies in the product and/or documentation. This may increase workload, so it’s important to include the collateral impact in your plans. Especially if the impact affects other features and other writers. A very typical example is any update to the settings or permissions sections.

Release notes

Some features and updates are silent, some go out with a bang. Here, cooperation with Product and Marketing is important. This doesn’t mean that the release notes should be turned into marketing slush. But Marketing might have a nice video that you can borrow…

For details, see Engage: Publish And Listen To The Feedback.

Third party products

Sometimes, using a third party product is necessary for your product (for example, analytics integration). How far you go, what level of detail you want, or can legally provide. Consulting your Legal department might help you resolve the issue (and prevent legal ramifications).

Know Your Audience

Defining your audience is an integral part of your information architecture. Now, you can take a more nuanced approach.

Even within a single product, audience types may vary – by skills, by permissions/roles, even by language (layman vs. expert). Some sections are for admins, some for regular users.

If you are dealing with technical documentation, ensure that your language matches your audience’s technical acumen.

Define Your Documentation Structure

Start by asking:

• What kind of content does the new feature need?

  • Introduction, reference guide, dictionary, how-to, educational bit…

• Does the extent of documentation warrant a whole new top-level section? Maybe even its own space or project? Or is a subpage in your documentation center enough?

• What’s the ideal order and nesting for new articles?

• How should you structure public/internal sections?

One VERY important thing to keep in mind here is that you’re not building a new Stonehenge. You can move pages around at will (well, you can in Confluence 🙂 ) to see what works and what doesn’t. Do not be afraid to experiment with the structure on any level – article, section, the entire doc set.

Define the Roles and Responsibilities

A documentation plan only works if people actually know their role in it. There is, of course, a writer who is responsible for documentation. The product owner/manager should be accountable for documentation – documentation is a part of the product – and they should ensure that the feature is released fully documented.

Even if your QA team reviews documentation before the release, we recommend identifying a subject-matter expert(s) to work with writers on iterations to review technical accuracy, especially in highly technical, industry-specific, or legal content. This will prevent nuances from getting lost in translation between the technical and user-friendly. Otherwise, errors and omissions will multiply and will be hard to fix at the later review stage.

Release and Communication

The ‘WHEN’ is a crucial part of planning your documentation because it determines the time that you have to write. Not just this particular feature but also others that you might work on in parallel. Of course, the time frame can change so it’s important to keep the information flow among writers, Product, and Engineering alive.

Here’s what you can consider in the planning phase.

• Will there be an early access/beta version of the feature that will need documentation?

• Will the new feature be released in one big GA or should we work with incremental releases?
  This might increase workload on the documentation team as they will have to re-open and re-write articles with each iteration. As a compromise, documentation may be released only for the GA.

• Do you need to coordinate with Marketing and Sales?

Communicating a new feature is usually a multi-team effort and should be an integral part of your planning efforts. Why?

Marketing may ask for a link to the future documentation article or release notes, which you should be able to construct before publishing. Product may also demand a ‘pre-release’ release notes article, especially if users' action is required for the actual release to work.

And then there are deprecations. Sure, planning often involves marking articles for deletion, but the less time you spend on writing, the more time you’re likely to spend on communicating the change well in advance.

For more information on handling publishing and communication, see Engage: Publish And Listen To The Feedback.

Let’s Put Your Plan Into Action

This one’s easy. Now you can start writing 🙂.