The Documentation Guide

If you’re reading this, you’ve probably subscribed to the idea that documentation is a part of the product and that it’s a process. That’s a great start and you’re literally halfway there. Maybe you already have a body of documentation that you’re trying to sort out. Maybe there’s a product with no docs. Or maybe you’re in a startup and the only thing you have is… an idea.

We wrote this guide to help you learn about various aspects of documentation life cycle management. Rather than telling you exactly what to do, we want you to learn to ask the right questions. Questions that only you can answer.

We outline what we believe are the best practices for designing and sustaining the framework for your documentation life cycle management. Think about the suggestions and questions in this guide and approach them from your own perspective, in your own environment, talk to your stakeholders.

Sooner or later, a clear vision will emerge.

This guide will still help you learn how to create or refine your documentation strategy and documentation life cycle.

Advice in this guide is tool agnostic - the principles behind good documentation are universal. A good article is a good article; a well-maintained documentation portal will help users irrespective of what tools were used to create it.

Some tool sets just make it much easier and efficient.

At K15t, we chose Confluence and the whole Atlassian ecosystem because together they remove tooling and process silos and allow teams to be on the literal same page at any moment of the product and documentation life cycle. We make specialized content management apps for Confluence that turn Confluence into a flexible all-in-one documentation suite that scales easily.

Devising Your Documentation Strategy

As you will see, documentation strategy and lifecycle management reach far beyond actual documentation. It’s a cross-functional team effort. The easier it is for everybody to be on the same page throughout the process, and the more your content management system integrates with assets of other teams, the easier your job and the better the documentation will be.

Documentation strategy sets the structure for how you go about managing your documentation and its life cycle – planning, creating, organizing, reviewing, publishing, and maintaining knowledge.

The primary goal is to create a single source of truth and processes that ensure documentation stays accurate, up-to-date, accessible, and impactful over time.

Just as any software or code is created, updated, and, sometimes, deprecated, the same applies to your documentation. You need tools – to create and manage your docs. And, as you work with other people in various capacities, such as writers, developers, product owners, designers, and your customers, you need to design the processes that will benefit everyone in that chain.

Five stages of the documentation life cycle

Broadly, you can divide the documentation life cycle into five stages. Don’t worry, we’ll discuss all of them in detail.

---

Stage 1
Plan: Before You Start Writing...

Before you write a single word, you need to figure out what needs to be documented, who it’s for, and where it should live.

Stage 2
Author: Write Documentation That Actually Gets Read

Now the writing begins. You bring in subject matter experts, organize your content clearly, and collaborate with others to make sure your documentation is accurate and useful.

Stage 3
Review: With a Little Help From Your Team

This step adds polish and helps you catch gaps, outdated details, or unclear instructions before your audience ever sees them.

Stage 4
Engage: Publish And Listen To The Feedback

Your documentation is published. This step is all about delivery, letting your target audience know, and gathering feedback.

Stage 5
Maintain: Documentation Without Losing Your Mind

Here’s the part most teams skip (and regret later). Knowledge only stays helpful if it stays accurate. Maintenance keeps your content relevant, up to date, and trustworthy.

---

Let’s look at some of the areas, subjects, and possible requirements you should consider and analyze before deciding on how, where, for whom, with what, and … for how much you handle your documentation needs.

Your Docs Strategy Starts with Your Product

The nature of your product, or whatever you’re documenting, has a profound impact on your documentation strategy. For example, ask yourself how people use your product – it can be a SaaS social media management platform, an Atlassian Marketplace app, a mobile phone utility, Human Resources onboarding guide, or a microwave.

Take the ‘sharpen’ tool in a photo editing app. The result depends on parameters of the specific photo such as pixel resolution, DPI, color depth, etc. Users may use different settings based on the output medium… In this case, you describe Lego bricks and help your users to understand how the product works.

Your product may also come in different flavors – free and professional, for MacOS and for Windows (and Linux). Then you should consider a tool that supports conditional content – often overlooked but incredibly powerful feature. Or you may need to version your documentation because your product releases come with semantic versioning (e.g. 1.1.2, 1.1.3, 2.0.0).

Release Cycle and Documentation Life Cycle

Release velocity (frequency) will impact your tooling decision, your process setup, and even your engagement strategy. A six-month release cycle will have different demands compared to a continuous delivery scenario in which individual development teams work along several swim lanes and you need to update your documentation several times a week.

For continuous delivery, your first priority is to avoid dependencies while ensuring everyone works off the same base. You don’t want Maggie to wait with her ready-to-go documentation while Conrad finishes his update next month. Meanwhile, you’re restructuring your entire doc set… These dependencies and efforts to get everyone on the same page from various branches can become huge blockers.

Ask yourself:

• Do you need to version your documentation to match product releases – your Documentation 2.3 should match the Product 2.3. Then there is the question of how many versions you want to display and/or support.

• Do you plan to provide early access documentation for your upcoming features?

These are not mere what-if scenarios. Scrutinizing the release aspects of your product will pay off in the future.

Your Team as Your Strategy Executor

There’s one thing all documentation teams have in common. They could use at least two more writers, which would be nice. But there are teams you’re bound to work with. Consider your stakeholders.

• Who is going to contribute – tech writers, product owners, engineers…

• Who are the subject matter experts?

• Who will review drafts?

• How do you get information from subject matter experts to writers?

• Can you get feedback from the Support team?

• etc.

Identify who has the required knowledge and can contribute, and set up your processes around it. Should we call it ‘distributed writing’?

And, again, your answers will impact the tooling and the number of seats you pay for in your license. A tool, or tool suite, that allows everyone to have access and progress quickly has an advantage over siloed solutions.

Tune Into Your Audience

Very often, your product type and user type (your audience) align. It’s not a hard rule, though. But you should always write for your audience and consider your style, tone of voice, structure, and even formatting parameters of your docs. Product documentation can have a narrow, specific target audience. On the other hand, your company’s onboarding guide targets literally every single role, from developers to receptionists and, therefore, must be written for a really broad readership.

In software, the correct estimation of users' technical prowess is often the key to making the documentation accessible. You want to be reassuring when the tech prowess is low and you can be more matter-of-fact when you’re documenting a pro-grade router. Avoiding tech jargon is always a good idea. Similarly, when documenting HR processes or legal guidelines, you want to avoid speaking in legalese that 90% of your employees won’t be able to interpret correctly.

Public, customers-only, or offline docs

The debate about whether you should make your documentation public or not is as old as the internet itself. You might be afraid that by putting it out there, you will reveal your secrets to the competition and want to make your documentation only available to your customers. On the other hand, a decision by one company to make their documentation public may force competitors to do the same.

Your public documentation, especially with a great search engine optimization (SEO) , can increase your brand awareness. AI crawlers will notice and your site will come up in search summaries. Your public docs site enables product and feature discovery, it shows technical evaluators that your documentation is reliable and supports self-service, and, in turn, increases the overall value of your product.

Internal documentation, as a standalone doc set or an expanded mirror of your public site, is another legitimate use case and will impact tooling selection. Confluence works especially great as an internal documentation tool because it serves as an authoring, content management, and output tool.

Ensure that your documentation tools and/or documentation portal supports some form of authentication without the need to provide actual paid-for seats to your authoring tool. Look for SAML SSO, token-based authentication, or federated login via Google, Microsoft, Apple, etc.

Some of your customers may require offline access to documentation. This is common for ultra-secure environments and some companies may even require documentation to be physically printable. In this case, consider tools that allow you to export your documentation, or its specific sections, into HTML, Word, PDF, or perhaps EPUB. You can also use such exports to provide early access to your docs to specific users.

Localization Is Not Just Translation

Broad international user base, multilingual countries, multinational corporations, contract requirements may add another must-have to your list. Your authoring and publishing tools must be able to support translations, and you will probably need someone to set up and manage the so-called ‘localization train’.

Which begs the question. Do you want to do translations in-house or work with a professional localization/internationalization service?

Remember, localization, or internationalization, is not just about translating words to other languages, so it always helps to approach localization of your documentation along with your product localization efforts.

Documentation and Compliance

Are you in a regulated industry? Medical, pharmaceutical, military, aerospace, etc. industries must often comply with requirements that go far beyond ISO and SOC2 standards. Following accessibility best practices is never a bad idea.

If you have any doubt or hint your documentation might be a subject to compliance or certification requirements and audits, check with your head of compliance and work with them on devising steps towards meeting certification criteria.

Documentation as a Part of Your Product

Ultimately, the process is a function of your specific requirements. Some companies just have a list of documentation tasks from which writers pick their tasks as they come. This, more often than not, leads to backlogs, detachment of writers from the product, and poor documentation.

Here we offer our recommendation based on the DocOps methodology

• Documentation is a part of the product, of the definition of done.
  This ensures that no feature is released without docs.

• Writers work as members of development teams.
  As writers become embedded into specific team(s) and participate in the team’s agile rituals, they will develop a much better understanding of their products – this speeds up knowledge transfer, improves planning, and results in better documentation.
  In non-technical teams, this can be implemented by assigning specific team members to write documentation and having an approval workflow set up (engineering, HR, etc.).

• Documentation ticket is a part of the dev team’s workflow.
  Treating documentation tickets as any other improves documentation visibility. Very often, developers offer help as subject matter experts to ensure that the story or epic is closed in time.

• Documentation is not code.
  Documentation is made with real human language; one idea can be expressed in several ways. Writers should be able to work with documentation in tools designed.

Choosing Your Tools

When talking about documentation, many writers, content managers, and information architects think only in terms of writing and content management. They take a shortcut when choosing a Content Management System (CMS) only to find out their tool can’t grow with the product.

Others have to resort to coding their own tools from scratch, just to get some elementary functionality, such as an expanding box. Customizations, or even building a CMS from scratch, will need resources – mostly time for small teams, or a lot of money for giant corporations.

On the other end of the scale are full-fledged, can-do-anything, hyper-flexible dedicated documentation solutions. But they tend to be extremely expensive, too complex for most teams and use cases, and closed to a point where subject-matter experts' reviews have taken place in external tools like Google Docs.

Look at the big picture. It’s easier to find a workaround for a formatting feature than to remove a cross-tool barrier that prevents your peers from working with you on documentation.

Your tooling will have to support your processes and the product/audience-driven requirements not just now but in 2–3 years’ time. Ideally longer, because migrating documentation is one of the most daunting tasks for content teams.

Choose the right tool for the job but make sure that it doesn’t introduce obstacles for your team’s effort.

Confused?

No need to be. As you have undoubtedly realized, the factors we discussed above are interconnected. Product and Audience. Audience and Localization. Your team and processes. And all that impacts tooling. Often, choices in one area define your options for another.

All roads lead to Documentation. Every process deficiency, every bug, every hiccup from every Product, Engineering, QA… will eventually surface in documentation. As a writer or docs manager, you have the superpower to point to individual issues before they accumulate.

The point of this what-if exercise is to make you think and ask the right questions. When you define the essentials, list down your requirements, even peculiarities that you find important, the image will emerge and become much clearer.

Let’s start planning documentation for the first feature.

One More Thing About Confluence

If you are using Confluence in your company, be assured that everything we mention in this guide can be achieved by taking advantage of the Atlassian ecosystem, combining Confluence, other Atlassian tools, and apps from the Atlassian Marketplace .

You can set up semantic versioning, conditional content, localization, and various integrations. If you already have Confluence, you already have a very viable documentation platform that you’re already paying for 🙂.

Writers on our team have tried a lot of tools over the years, and when it comes to documentation, Confluence hits the sweet spot . It’s flexible, collaborative, scalable, with a great learning curve. Whether you’re a tech writer, a support lead, or just someone who knows things and wants to share them.