Thinking Strategically About Documentation

As a technical writer, you will contribute to different kinds of documentation projects. It’s important that documentation responsibilities are aligned with a coherent strategy.

One of the biggest things to know about documentation (that people don’t think about) is that the word documentation is polysemous. The various meanings pretty much guarantee that at more chaotic employers you will be pulled in different directions unless you have a clear strategy or posture when it comes to working as a technical writer.

I didn’t go into the various definitions in my previous post, but there are three main meanings at play in a company:

1. Official information source — The canonical guide to a product or service.
2. Normative guide — This formalizes a decision and guides the behaviour of people (think project documentation, process documentation).
3. Evidential material — Evidence that a control, process, or system is in place.

These three senses of documentation often overlap: team process documentation is from an authoritative source (a manager) and can be a form of evidence that the team does something (for a compliance audit), but it also guides behaviour (the process is only valid if people are held accountable/follow it). Sometimes these definitions come apart: a user manual describes how to use or complete tasks. It’s not a guide to how people should go about working (in the same sense as process documentation) or a guide to what should be done as part of a project. And the same piece of documentation can function differently depending on how an engineering team operates. An OpenAPI spec, depending on spec-first or code-first engineering, can be either guide the writing of code or describe what has already been written.

Technical writers can contribute to all three kinds of documentation! The problem arises when employers fail to carefully define lanes of responsibility and prioritize work for technical writers. And, unfortunately, this is particularly common for teams where they feel the need for a technical writer, but don’t have experience with one on staff. In this case, the company is at the bottom of the docs hierarchy of needs. Any documentation is good documentation, and the incoming technical writers are supposed to deliver the solution to their problems. Managers and leaders from across the company will see you as a resource they can use to help with their documentation needs, in whatever ways they’ve internalized the meaning of the word documentation.

This is a recipe for chaos and the technical writer becoming overwhelmed. And it’s why it’s important (as a technical writer) that you build this shared understanding with your immediate manager and ensure it’s communicated to your company as a whole.

Having a clear sense of why, what, who, where, and how is part of what I call a documentation posture or strategy. Aligning your work with a strategy involves framing how readers will interact with your output and where your core responsibilities fall.. These can then inform your metrics for evaluating your output and ultimately, which platforms you’ll work with. Having an explicit, shared understanding between you and your manager is key for your success as a technical writer.

This post is a bit of a brain dump of terminology used in software companies. By the end, however, you’ll have an understanding of what goes into framing a coherent docs strategy and ways in which you can define your responsibilities as a writer. Hopefully this is helpful to leaders considering working with technical writers, or technical writers trying to make sense of vague job postings!

Products, audiences, and support models

Since software products and support models can take various forms, documentation sites look very different from company to company. A lot of technical writing materials assume that there’s a single thing, “docs”, that we produce. But I think that there’s differences in the kind of output that are worth describing when framing your documentation posture. So, this post will be a brief guide to the different kinds of docs sites that you might have to contribute to as a technical writer working at a software as a service (SaaS) company.

For this post, I want to focus on a particular kind of thing that technical writers are uniquely positioned to contribute to: documentation sites. A documentation site is an electronic resource that provides material that meets documentation needs, and can be publicly available or locked down to require user logins. They are a living resource that is updated as your software product changes (unlike hardware manuals!). Documentation is a (typically written) electronic resource that lives on the docs site. It could be served as web pages, PDFs, videos, etc. and it can be authored through a variety of tools.

Unsurprisingly, there is no single or standard way of doing this. Understanding the audience’s needs is key to choosing the right solution. Here are a few different models for user needs that documentation sites can address:

• Developers need materials that enable them to build with a software development kit (SDK) or application programming interface (API).
• Administrators need guides oriented around common configuration and maintenance tasks for complex, multi-user apps.
• Users need guides on how to complete certain tasks within an application (typically through a graphical user interface).
• Users/admins/developers should have the option to self-support and troubleshoot common issues that arise when trying to use your product.
• Internal staff need resources to provide support to customers experiencing problems with your software.
• Internal staff must be able to easily create and find resources on their projects or how to work with other teams.
• Internal staff need to demonstrate that they know what to do in certain circumstances and evidence to external auditors that processes exist.

In choosing a strategy, you need to have a clear sense of why users are coming to find documentation, how they’re navigating through it, and how you’ll evaluate whether what you are doing is useful. This will vary based on what your product is, who your product is for, what they’re trying to do with it, and how much involvement your customer facing teams have in the support process.

In the next section, I’ll break these down into central categories, and explain some of the tools that are used in building and maintaining them, and why you might adopt any mixture of these platforms.

Three models of documentation practice

So! I think bearing in mind the multiple meanings of documentation and the different product categories, there are three main approaches to meeting those needs: there are comprehensive guides, enhancements for user experience, and resources for normative guidance/evidence. As a technical writer, I’ve interviewed for roles involving, or worked on, each of these in some capacity. Each of these needs is better supported by different solutions, so I’ll explore each a bit more closely.

Comprehensive guides

The first category emphasizes documentation as comprehensive guides or resources. In these instances, the goal is to provide a resource that is like the full operational manual to your software. These are most often in place for products where they are intended to be consumed by technical, engaged users who are comfortable getting into the details of how your product functions. Often these products are for developers — who interact with your product through code — but there are cases where a similar level of attention is necessary for products with user interfaces as well.

It’s important for scenarios where your readers need to build understanding, but also refer to how the parts work to achieve their goals. When contributing to these sites, you’re trying to provide feature coverage. If it’s for administrators, you’ll provide guidance on how to configure integrations, user categories, and permissions. If it’s for end users, you’ll cover the main features and workflows in your app. Once you’ve achieved coverage and are able to maintain it, you can move on to focus on improving the experience and offering tailored learning paths or fancy interactive features.

In this case, you’ll often see webpages that use terms like “developer portal”, “API Guide”, or “Docs site”. You can find these at developer.product-name.com or docs.product-name.com (with the notable exception of Google Docs). These sites are often focussed on displaying content in an easy to read manner, and built to quickly get skilled people into interacting with your product through tutorials and code samples. Larger tables of reference pages are built from automated resources, like an OpenAPI spec — a standard way of describing an API and how it will respond to requests.

A Note on Content Architecture: CCMSs and DITA

While many of the tools listed below (Static Site Generators, or SSGs) focus on generating a single, static web experience (a single endpoint), large, complex organizations with numerous products, versions, or regulatory requirements often adopt a Component Content Management System (CCMS), frequently built around the DITA (Darwin Information Typing Architecture) standard. This is not a site type, but rather a content architecture where content is broken into reusable topics. This approach allows a single source of truth to be published to many endpoints (websites, PDFs, embedded help in apps) — which is essential for large enterprise products. This post largely focuses on web endpoints, so I’m including this here for the sake of completeness!

Here’s a quick breakdown of how these three categories come apart:

If you’re hiring a technical writer to contribute to these kinds of docs, you’ll want them working closely with your engineering team. They’ll need access to the API and test environments so they can verify that code samples function. Users might rely on the information architecture to explore, but often use a combination of search tactics to find the information that they need and quickly leave the site.

The bulk of technical writer resources on the internet are geared towards technical writers functioning in this kind of space. Why? Well, documentation is necessary for these products to be used. If you’re interacting with an API, there isn’t a graphical interface to guide you to completing key tasks. For apps that focus on user experience, however, things differ.

Enhancements for UX

The second approach is to build resources to supplement a user’s experience of a product. Generally speaking, companies that adopt this approach tend to have intuitive products or onboarding for user bases that are less likely to spend time working with specific references. These sites are less focused on in-depth product reference and more on providing resources that develop and enhance a user’s journey with a product. They may be built to support and develop skills through structured learning. Like other docs, these could be delivered publicly or as part of a customer portal.

These resources are part of the overall world of customer experience (CX). If you are contributing to this part of a docs strategy, you will be best served working within the CX function. Overall, the metrics here are deflection and efficiency. Is there a reduction in support tickets after publishing an article about a common issue? Are onboarding goals being met? Are certifications being maintained?

Rather than expecting users to navigate through these resources, there’s an emphasis on searchability and task-oriented content. There may be a higher volume of shorter, highly specific articles developed along with support teams. In some cases, there may be no visible navigation structure for external audiences (knowledge bases built explicitly to be searched, rather than browsed).

These kinds of resources live at domains like help.product-name.com or learn.product-name.com. They often make sense in contexts when there’s a larger or broader user-base that is less engaged with the technical details of the product, though some platforms make sense when it’s important to track or reward the development of knowledge.

When contributing to these systems, technical writers usually partner with Support and Customer Success to identify high-volume pain points. It’s often the case that technical writers aren’t the sole contributor, or these systems are owned by people outside of the function entirely. Learning systems in particular are highly multi-modal, and dedicated instructional design professionals will work on LMSes. If a support team practices knowledge-centered service, support team members might author articles that you edit prior to external publication. There’s a variety of models here.

A quick note: training is an activity or event, but it is also sometimes used as a content type. Slipping between the two can happen here, just like with documentation! An article can be a self-training resource, an LMS is a guided experience that supports learning and training.

Guidance and evidence

Finally, there is the documentation that keeps the company running smoothly, ensures internal alignment, and protects the organization legally. These are rarely public facing, but as a technical writer, you’re often regarded as the expert on information architecture, governance, and clarity.

Common goals for these kinds of artifacts are alignment and compliance. Internal resources help teams align by making sure that engineers use the same UI components, new hires get up to speed quickly, and that decisions are logged and searchable. For compliance, the goal is often purely evidential — demonstrating that certain controls and processes exist and are followed.

Writers engaged in this kind of work are often embedded in ops or services teams, and work assignments come in to support experts or managers within a larger company. A technical writer has a domain knowledge in how to communicate processes clearly in writing that managers might not have, and help with standards and clarity on these kinds of documents.

Writers might not write every internal policy, but they can help create efficient templates, manage the structure of the wiki or repositories, and help enforce quality standards to ensure that critical knowledge is accessible and trusted. This kind of internal documentation has the potential to be the biggest spot where responsibilities can slip — if you are a technical writer embedded in an engineering team, you might produce internal documentation on Confluence regularly. This kind of expertise will look tempting to directors outside of your team.

Developing a posture

One of the core challenges of being a technical writer in changing or smaller companies isn’t just writing, but navigating the views of directors and managers from across a company. I previously talked about building a shared expectation with your immediate manager. Without a clear documentation posture on all three needs, it’s very easy to be pulled in every direction: struggling to maintain product guides, supplementing user support, and managing internal organizational knowledge.

This is why developing a clear documentation posture is critical for both your success and the coherence of your company’s knowledge ecosystem.

You should think of it as an explicit, shared agreement on four points:

1. Core responsibilities: For both technical writers and other internal staff. Which is your primary focus as a technical writer? Who contributes to other forms of documentation?
2. Success metrics: Adoption? Deflection rates? Internal efficiency and compliance?
3. Governance: Who owns the content? Who is responsible for the information architecture?
4. Platforms: Where will the content go? What tools and permissions need to be in place to work at scale for that platform?

By answering these questions and having a clear sense of platforms and responsibilities, you can move from having “docs” as a vague “need” or “requirement” and have a coherent plan for working with your technical writers as strategic hires within an organization. You can assess whether your docs are meeting needs, and come up with plans for improvement. This kind of clarity serves as a strong defense against competing priorities, reduces burnout, and sets up your staff members for success.