data-informed documentation on This is important

Inform a small documentation project with data

Tue, 27 Oct 2026 10:35:00 +0000

When you take on a small documentation project, you can inform each step with data. It might seem like overkill. Small projects are often ones that you tend to consciously plan or build a process around — they’re mostly an execution task:

An interrupt from a colleague that you pick up while on triage, letting you know that they changed the title of a chart in a dashboard.
A tag from someone on a Slack thread where a customer is confused about when a specific type of query is run.
A page quality feedback comment asking how often the data in a dashboard is updated.

It’s easy to treat each small documentation request as an important task to deliver, especially with AI-driven workflows. Avoid bloating the content, and thus the context that your reader must absorb, by using data to inform even small documentation requests and determine whether to write something at all.

When you work on a project this small, the phases look somewhat different from those of a medium or large-sized project:

You also want to keep the time that you spend on each phase in scale with the size of the project itself. For a small documentation project, spend the most time planning the update, less time making the update, and even less time on evaluating the outcomes of your update.

Plan small documentation updates

When planning a small documentation update, examine the request and determine whether a documentation update is the right approach. The request is the first, and most important, data source. As part of planning the project, you want to identify the actual problem leading people to request the documentation be updated. Based on that, you can then evaluate if a documentation update is the right approach.

Choose how much data, and which sources to use when planning your small documentation updates depending on your analytics capacity :

Capacity	Key data sources
None or Basic	Original request Product exploration
Growing or Defined	Page quality feedback Product exploration, Documentation exploration
Mature	A wide variety of customer submissions and research

Evaluate the request

When evaluating the request, take a data-informed approach and use the following resources to identify the root cause and qualify the request:

Customer submissions

Page quality feedback
Support cases
Community forum questions
AI chatbot conversations
MCP server interactions
Social media posts
Search terms
Slack posts
GitHub issues and PRs

Research

Product exploration
Documentation exploration

No matter what data sources you use to contextualize the documentation request, consider the following:

What is the request?
How often is the request being made?
Who is making the request, both how many users and of which type?

These are essentially triage questions, and the answers can reveal that something is inaccurate, needs clarification, or can lead to data loss or a security issue for customers.

For example, given the following documentation requests that you might receive:

An anonymous comment requesting details about how often the data in a dashboard is updated, so you might want to add a note about latency to the documentation.
A support case requesting guidance for scheduling a data export from the dashboard to run automatically, so you might want to add a task or example to the documentation.
An internal solutions engineer asks for details in Slack about how the data in a specific dashboard column is calculated, so you might want to add a reference table to the documentation.

With just the data in the request alone, it might seem like only one person is asking this infrequently. If you attempted to situate the requests on the following chart, they might all be an “A”:

But what is actually true? For each of these requests, even the straightforward accuracy, clarification, and risky ones, you can provide better outcomes for your readers by adding data to inform your planning process.

You don’t need to use every data source available to you, especially if you have limited analytics capacity, but you want to look at a few different types to qualify the request and be able to answer the earlier questions with a reasonable degree of certainty.

For example, consider customer submissions :

Data source	Questions
Page quality feedback	Have customers submitted feedback about this topic before? Is there an existing ticket for this request?
Support cases/chats	How many customers are contacting support about this issue? Who are they?
Community forum questions	Are customers asking questions about this issue?
AI chatbot conversations	Are customers asking the AI chatbot on the docs for help with this?
MCP server interactions	Are customers asking their AI assistants for information about this?
Social media	Are customers posting on Reddit, LinkedIn, or elsewhere about this?
Search terms	Are there unsuccessful searches on the docs site for this information?
GitHub issues and PRs	Are there existing issues open about this request? Has anyone opened a PR attempting to update the documentation?

From the volume of requests alone, you might recognize that lots of different customers are asking for this information pretty frequently — in which case, this is either an urgent small documentation task or a larger task that needs a medium-sized approach.

The data that you collect about a request might move it from an “A” to more of a “C” or a “D”, in which case delivering documentation becomes more relevant.

For example, take the request to add information about how frequently the data in a dashboard is updated. When you go to investigate how common of a question that is, you might see a wide variety of other questions about the same dashboard. For example:

How is the data in the dashboard calculated?
Can I access the raw data behind the dashboard?
How can I export and save the data on a schedule?

You can then decide what to do next — expand the scope of your project or not. You can choose to identify, record, and address all three of these requests at the same time — effectively promoting the task to a medium-sized project. Or, you can note the larger (scope creep) tasks for later and address only the small-scoped item to add the data refresh details for now.

If you continue with the small task, add research to further qualify the request and plan your writing task :

Qualify the customer

When analyzing customer submissions , you’re trying to identify roughly how many customers are affected or share the request, and what they might have in common. This qualifying step helps you determine if the request is a universal concern (and thus a good idea to document), or something specific to a customer’s configuration (and thus likely irrelevant to add to documentation).

For example, in response to page quality feedback requesting details about how often the data in a dashboard is updated, you might perform research to answer the following questions about the customer experience:

Who reported the issue? Was it an internal or external customer? If an internal customer, are they acting on behalf of an external customer?
Is the issue, or confusion about the issue, reflected in (additional) page quality feedback, support cases, or questions posted to the product forum or community sites?
Are people searching terms like “latency”, “delay”, or “not as expected” for this dashboard?

Explore the product and its code

Further qualify the context of the request by answering the following questions about the product with product research .

For example, in response to a request for details about how often the data in a dashboard is updated, identify what the latency is and why it exists:

Test the product and attempt to replicate the latency.
Review the dashboard and examine if it provides any details directly, in descriptions or tooltips
Determine if the latency is intentional, and associated with a scheduled process with a fixed refresh rate that you can easily document
Identify whether the refresh rate is supposed to be immediate. Perhaps there is a known limitation of the product that might get fixed, but not anytime soon, causing it to be intermittently longer.
Establish if the latency is actually a fluke due to one customer’s system configuration, and not something happening to other customers.

How easily you can answer these questions reflects the scope of the task and the analytics capacity of your organization. If the answers are easy to find, the task stays small and your analytics capacity might be growing or more mature than that. If the answers are undocumented internally, not available in code that you or AI tools can access, or otherwise difficult to find, the project can start to creep in scope due to unavailable data and context. Avoiding that scope creep is why it matters to identify your analytics capacity before deciding when and whether to add data to a project.

Refer to existing documentation

You can also explore the documentation itself to help plan your approach and qualify the request .

Review the existing documentation. For the example of investigating dashboard latency, review the following:

Check whether the information is already documented, but perhaps hard to find. Is there a page for all dashboards that mentions latency, but it isn’t linked from individual dashboard pages consistently?
Determine if there is a standard template used across all dashboards that wasn’t used for this one, intentionally or otherwise. Do other dashboard docs mention latency numbers? Is there a standard for how to document a data refresh rate?

Leave lessons for your future self and agent collaborators

If you use AI in your planning process (and your drafting process), the context gained from reviewing similar pages can be easily skipped because agents naively follow prompts. To prevent agents from updating one page without checking related pages, consider adding something to the file that instructs the agent behavior (AGENTS.MD, CLAUDE.MD) to review similar documentation pages for necessary changes when making documentation changes to one page.

With the research complete, finish your data-informed plan.

Plan what changes to make and why

After performing research to evaluate and qualify the request, you can plan what changes to make to the documentation, and justify why:

What you found in the data	Action to take
Latency of up to 4 hours is expected.	Add a note to the dashboard documentation.
Misconfigured settings can cause a refresh delay.	Add a note to the dashboard documentation.
A bug in the data pipeline causes latency for some customers.	Add a known issue to the product release notes.
One customer misconfigured a setting and thought there was latency.	Do nothing in the documentation.
Latency was documented but on a main page about all dashboards, not a specific dashboard page.	Add the latency, or a link to the main page, to each dashboard page.

If you determine that writing a small documentation update is the right path, continue with that part of the process, otherwise skip to evaluating your decision.

Write small documentation updates

In planning, you identified whether there is truly a documentation issue. Now, you execute and deliver on your data-informed plan:

Keep it small and write a documentation update. For example, in the case of the dashboard latency, your data-informed plan indicates that this is a commonly asked question shared by numerous customers, so you add a note to the dashboard documentation.

Tech writer as proactive product advocate

Embrace the expanded role of a tech writer as a proactive product advocate. Even when adding a small documentation update, consider meeting with the team that maintains the dashboard to identify if there is an in-product option to make the latency more apparent on the dashboard itself, such as by adding a “last updated” timestamp in the page footer.
Recognize scope creep and pivot to a medium-sized project. Your data-informed planning might have revealed that the seemingly small request is actually a medium-sized project if you act on it properly.

For example, a request to clarify how the data in the dashboard is calculated involves updating the existing dashboard templates for your documentation site to include a data dictionary with a column detailing how calculations are derived. That involves multiple teams to gather the necessary data, and a few weeks (instead of a couple of hours) to make the changes that are most helpful to the customer.

Without using data to inform your plan for handling this request, you might have added information about how the data for a specific column was calculated for one dashboard, and not considered improving the other dashboards (because that wasn’t requested).
Split the request to keep scope small. As another example, for a request to export and save the data on a schedule, your data-informed plan reveals that this is a frequent question asked by a particular cohort of users. Unfortunately, you have limited time to deliver the request. As a result, you take a twofold approach:
- Add a short task with steps for how to export and save the data on a schedule
- File a ticket to recommend adding a worked, end-to-end example of exporting and saving a specific slice of the data on a weekly schedule.

If you use AI in your drafting process, it can be easier to add data into your workflow, but the size of a small documentation change can limit the utility of adding data in this phase. Some practical examples of using data with AI agents is to use your knowledge of the existing code base to prompt an agent to copy the structure of a note on another page, or to create a reusable snippet with some existing note text, and add that to a documentation page. You can rely on your documentation research to take AI-enhanced shortcuts.

Guard against context bloat

A risk of using AI in your writing process , even in a data-informed practice, is that it is easier to respond to every request by automatically delivering on it. Request received in a Slack thread? Summon an agent immediately to make the requested update!

That sort of responsiveness can seem like ideal customer service, but it can also lead to bloated content that contains irrelevant information.

Knowing that AI agents are increasingly consuming your content might motivate you to add more content than you might otherwise, so that the agents have all the context available to them. However, if you continually make small updates to your documentation, adding new bits of information when requested, the key points of the content can get lost.

As Dachary Carey has discovered with her research, such as in Agent Web Fetch Spelunking, agents can miss content buried in large pages, and they have limited context windows.

If you have too much content, you risk context bloat and distracting your human and AI-powered content consumers. Instead, take the time to plan and use data to inform even small documentation changes. Contribute your expertise as a user advocate, curating the documentation experience.

Evaluate small documentation updates

When evaluating a small documentation update, your main goal is to assess whether you sufficiently addressed the original request. The data you use to inform the project helps you reduce uncertainty about your direction, implementation, and validate the outcomes.

Small changes to the documentation often aren’t noticed by customers, so aggregate quantitative metrics don’t show any measurable difference. As a result, how you evaluate the change looks different from a medium-sized or large project.

Based on your uncertainty about the change, the scope of the change, and the amount of data in support of the change, choose different levels of effort when evaluating the change:

Skip the evaluation stage entirely! If you don’t have any uncertainty about your decision (and neither does your leadership team), you can skip evaluating the change. This is especially true if you have a basic or growing analytics capacity. Trust your expertise and move on to the next priority.
Follow up with the original requestor. Talk to them and validate whether the issue is addressed, and whether they’ve received or have any additional relevant feedback. This approach has the advantage of letting you acknowledge the feedback and communicate the actions you took, hopefully turning the requester into an ongoing source of documentation feedback.
Check in on qualitative data in two months. A direct conversation with the requestor isn’t always possible. For example, the request might be many months old, and you’ve just now had time to deliver on it, or if the request came in anonymously through page quality feedback. In those cases, make a calendar reminder for two months after the change was published to see if there were any measurable changes in qualitative data sources, such as support cases or AI chatbot conversations .
Assess a full before and after data baseline. If you have a mature analytics capacity , or if you might replicate a small change on a larger scale if they prove useful (such as a full overhaul of in-product dashboard documentation), draw comparisons across many data sources after the change with a time period before the change. Compare the two months after the change with either the two months before the change, or use the same time period of the previous year to account for seasonality.

With this more elaborate approach, you might want to review the following data sources :

Data source	What to look for
Page quality feedback	Do you still get feedback comments about the confusion that led folks to write in?
Support cases	Do you still get cases asking about this thing that you clarified?
AI chatbot conversations	Does the chatbot answer the questions more clearly and correctly?
Search terms	Do search terms about the issue find results, or have a higher % of clicks on the page that you updated? Search volume might be the same (or higher), but the journeys to get to the relevant information (the page you updated) are hopefully shorter.
Page views and click activity	If you updated only the release notes, you can review the number of page views and click interactions with the note that you added.
Product telemetry	If you updated only the product, look at usage of the page that you updated.

If you use quantitative sources, remember that the purely quantitative sources of data only reveal impressions, not understanding or direct interaction. They help you assess whether the change reached your users, but not whether they actually read it.

Evaluate a choice to not write documentation

If you decide not to make a documentation update based on the data you consulted in the planning stage and instead decide to make an update to the product experience, you can evaluate that choice too!

For example, you added an on-page description and some tooltips for more confusing terms for a dashboard in the product, rather than adding a note to the documentation about the dashboard.

How do you know if those changes were effective on their own and don’t need to be partnered with additional documentation updates? Review additional data sources from customers :

Search terms and MCP server interactions to evaluate if people (with or without AI agent assistance) are still looking for information about this dashboard and not finding it.
Support case details and chat transcripts to identify if people are contacting your support team with questions about this dashboard, even after the change was made.
Questions in Slack, GitHub issues, or the community forum to identify if there are more or fewer questions about this issue.

In addition to changes in feedback patterns, the amount of feedback that you see from customers is also relevant. If you only see a few requests, or a few pieces of feedback about this issue over a quarter, the data isn’t large enough to treat as a representative sample.

An absence of data can be a good sign, but only in comparison to a relevant baseline. For example, if there was a strong pattern of consistent support cases for this dashboard, or search queries for the confusing term, and after the change you make there are no longer support cases or search queries for the term, that drop-off is a likely indication of success.

On the other hand, if customer submission data sources remain the same after the change, it’s possible that your change wasn’t effective. An even clearer signal is if requests to update the documentation remain consistent, or resume. In that case, return to your planning data sources, collecting and analyzing more to identify whether to actually update the documentation.

Practice data-informed documentation on a small project

Taking the time to inform even small documentation projects with data strategically ensures that your content remains relevant and useful for your readers. Not all requests need to result in documentation updates, and not all seemingly small requests stay small.

By taking a data-informed approach, you can effectively deliver relevant, curated content updates without unexpected scope creep or bloated pages that confuse human readers and AI agents they might use.

Inform a medium-sized documentation project with data

Tue, 27 Oct 2026 10:33:00 +0000

If you are about to start a medium-sized documentation project, you can inform each step of the process with data. If you do, you can more easily assess the scope of the work, prioritize and plan the implementation, and write more relevant content.

A medium-sized project is one that might take you a week or two of work, like a new feature that needs one or two new documentation topics, or a few different pages that need to be updated with new content for some to-be-released functionality.

For example, you might be writing medium-sized documentation updates for one of the following features:

An interactive workflow to create and assign tickets to specific users
A new type of widget that can be added to a dashboard
A new SQL function

In this post, I’ll cover how to use data to inform each phase of a medium-sized documentation project like one of those examples:

Planning and writing are often intertwined

For a medium-sized project, planning and writing inform each other. Rather than creating a plan in full, then starting to write, you might go back and forth, acting on some plans as soon as you make them and expanding your plan as you learn new information about the project scope that wasn’t clear when you started. This is common when documenting new functionality — it’s still in development, so the scope often isn’t predetermined and can’t be planned for fully in advance!

Plan medium-sized documentation updates

Planning a medium-sized writing task involves identifying the following:

What is being built?
What do customers expect from it?
What already exists in the documentation?

Use these discovery steps to identify the scope of the project. For example, if your engineering team is adding a new type of dashboard widget that animates images in a repeating pattern, you can use the following data sources to help plan:

Expertise

Business understanding

Research

User research
Product exploration
Documentation exploration
Competitive analysis

System

Documentation metadata

Customer submissions

Feature requests
Customer success call transcripts
GitHub issues or PRs
Search terms
Product reviews
Community forum posts

The planning process relies mostly on qualitative data, so you can inform it with data at most analytics capacity levels. If your organization has a more basic analytics capacity, you can rely more heavily on the data collected through research. If you have a more mature analytics capacity, you can add the more tool and expertise-dependent quantitative analysis.

Plan for maintenance

When you plan to add new pages and content, consider your future self and plan for maintenance too. For example, if you add screenshots of the new dashboard widget, place them in a shared location and record and share the assets used to create them, such as an example dashboard in a shared staging environment. Consider recording the research artifacts that you use to inform your plan in a longer-lived dashboard or collection that is shared with others. This practice of storing your data artifacts can help accelerate the practice of using data to inform future documentation tasks too!

The results of your data collection informs the decisions that you make as part of your documentation plan, namely what types of content to write, how much to write, and where to place the content. Start by considering your expertise.

Rely on your expertise

To determine the release phase, priority, and goals of the project, rely on your expertise.

Expertise

Business understanding

Your business understanding can help you identify why the new functionality is being implemented in the product at all, and what the business is hoping might happen as a result of this new functionality being available. For example, this can guide you in deciding what example to use in a task, or whether a customer might be improving an existing manual workflow with one that is more automated now with the new feature launch.

Your knowledge of the release process and planned priorities can also inform what to write. For example:

In the case of a new dashboard widget that animates images in a repeating pattern, it is an early stage feature that is low priority, so you might only plan a basic task and reference content about how to add the widget to a dashboard and what settings can be configured.
For a new SQL function becoming generally available that unblocks a major customer use case, you might plan a basic reference and multiple detailed end-to-end examples describing the function for the specific use case.
For an interactive workflow to create and assign tickets to specific users, the workflow is the first of many steps to target a new customer base, so while it is an early stage feature it is also crucial for the business strategy. As a result, you plan to deliver a task, a concept, and end-to-end example about the feature. As a lower priority, but planned to align with a marketing launch, you can add tutorials and extra screenshots.

I recommend a similar strategy for building out minimum-viable documentation for a product, and it is still relevant after you have a more full set of documentation to consider.

Beyond considering your understanding of the business and its priorities, you can perform targeted research to inform your documentation plan with data.

Perform research

Inform your plan for the medium-sized documentation updates by performing targeted research to identify what and how much to write. Your main objective is to know as much as you can about the feature — why it’s being built, who it’s for, how it works — to write the best content that you can.

Research

User research
Product exploration
Competitive analysis

User research

To identify customer expectations to help identify what content to write, how much to write, and where to place it, perform user research.

Research

User research

Depending on your analytics capacity , user research might be formal interviews guided by a qualified user researcher, a short conversation with a specific customer that offered feedback about the product, a survey sent to existing customers, or notes taken by design or product leadership as part of the planning and development of the new feature.

Rely on the user research available to you, if any, to inform your documentation plan:

Identify if the target audience of an interactive workflow is likely to be familiar with the relevant tasks involved, or whether it is very new, and therefore they’d want a detailed walkthrough.
Identify preexisting mental models or customer expectations about dashboard widget capabilities that might be informed by the current dashboard widgets, or widgets available from popular competitors that your customers also use.
Identify what key use cases and problems the new feature might resolve for customers.
Define learning outcomes for your content informed by key use cases, such as “Can successfully add a spiral image to the dashboard widget”.

You can use the audience understanding that you build through user research to define details of a task or conceptual introduction to provide for a given feature.

For example, with a new dashboard widget that animates images in a repeating pattern, determine if there are specific customer use cases that led to the development of this widget. Perhaps a hypnosis service company has agreed to purchase your product if this widget is built, so it only has one key use case, but it is a critical one. Additional research and discussions with the product management and design teams reveal that they expect the widget to also be useful to customers nostalgic for Geocities website design and targeting the retro web market.

In addition to user research, you must explore the product itself (if possible).

Product research

Product research is a data gathering exercise , and it’s one that we’re intimately familiar with as technical writers. No matter what your analytics capacity is , you can explore the product and your documentation as a data collection exercise to plan the shape of your project work.

When you perform product research, you can experiment directly with the product, if you have access (and it’s complete enough to do so), you can explore the code directly, or use AI agents as a data gathering tool to either answer specific questions about the product or identify relevant sections of the code to read and review yourself.

Using AI tools for research can risk introducing inaccurate content and assumptions, so if you use AI-based tools for code-answerable questions, prompt the tool to cite specific files (and check its work), include reminders about feature flags or other gates that might affect feature visibility, and verify any claims about the user interface with independent in-product explorations if possible. Consider standardizing guidance in a shared skill.

When you perform product research, especially for a medium-sized project for net-new functionality, collect as much data as you can about the new feature, especially how it works:

What is changing?
What is being built?
How complex is the feature?
What is the entry point?
Is the feature being added to an existing part of the product, or a new location?
How easy is the feature to use?
Are there missing steps or confusing workflows?

The value of a strategic product advocate

Identifying issues like confusing product design or opportunities for alignment with preexisting product features in the planning stage is valuable so that you can give feedback about the design or implementation. As a customer advocate, you can make your strategic value as a technical writer clear.

Use this research to establish the scope of the feature that you plan to document. For a complex feature like a new authentication method for the product or anything that involves an integration with an Amazon product, writing documentation can take more effort. A simple feature, such as the tenth type of dashboard widget that has been added to the product, can be more straightforward to document.

Defining the scope of the project is an iterative and interrogative process. Don’t take the initial scope that you discover as the planned forever scope. As feature development progresses, the scope of the feature can change. What you initially discovered at the start of your research might be an incomplete scope.

These planning and research tasks share some similarities with those that you’d perform for a large project, but they’re different for the feature. In a medium-sized project, where you’re documenting something like a new dashboard widget, there might be more design planning and definition of the future state of the content. The future state planning is present in a large project, and more elaborate due to size, but often more constrained by existing content or project scale. With a medium-sized project, you’re limited mostly by time and priority of the project—namely, what else you’re doing at the same time.

Competitive analysis

For a medium-sized documentation project, it sometimes makes sense to perform a small amount of competitive analysis to gather data to inform your documentation plan.

Research

Competitive analysis

By performing a review of competitor documentation for similar features on the market, you can determine and validate use cases guiding feature development. This kind of review can also help you identify if there are interesting or relevant ways that competitors document the same kind of functionality. Maybe you want to borrow something from their content design, or identify a pattern that you want to avoid.

A competitive review can also help you understand what terminology customers might be familiar with, identifying keywords that you might want to include when writing your content.

Keep a competitive analysis short and contained for a medium-sized project, limiting it to validation and discovery.

It might be tempting to use AI tools for a quick competitive analysis , but I’d caution against relying fully on AI output for this research task. AI tools retrieve content according to what you prompt, thus making organic discovery of content display tactics less likely. It’s a best practice to review the cited sources manually to validate relevance and accuracy, so while you might use AI tools to identify relevant pages in competitor documentation, review the content yourself for relevant patterns and insights.

After performing different kinds of research yourself, you can review other qualitative data sources available to you for some additional planning context.

Examine customer data

If you don’t have much opportunity to perform user research, or if you have a limited understanding of the business, you might want to review different qualitative data sources available to you.

Customer submissions

Feature requests
Customer success call transcripts
GitHub issues or PRs
Search terms
Product reviews
Community forum posts

Customer submissions can be a revealing data source for use cases, terminology, conceptual mental models, and expectations, all of which are valuable for informing your documentation plan.

With data sources like feature requests, product reviews, or call transcripts with internal folks and customers, you can gather information about how customers talk about the new interactive workflow being developed, or the exciting new dashboard widget.

For example, based on customer feature requests in support cases and GitHub issues, as well as customer success call transcripts, you recognize that customers are concerned about the performance of dashboard widgets, which is unclear for most widgets. As a result, you can add an item to your documentation plan to test and provide details about the performance of the new dashboard widget that animates a repeating image.

You might not be able to prioritize that type of content for an early-stage, low priority feature, but by using data to inform your plan, you’re going beyond the basics of “document the feature” and instead being more strategic, planning to deliver more practical and relevant content to users.

A risk with these data analysis phases, compiling business understanding and user research with customer-submitted data, is that you weight internal assumptions and plans for product positioning more heavily than your findings from user research and customer data. Just because your organization wants something to be true and wants your customers to understand something about the new feature based on the planned marketing and product positioning, doesn’t mean that they will. You need to understand the customer’s mental model and preexisting expectations to write effective content — and that can require more effortful research and data analysis.

Use data to define what to write and where to place it

After you use your expertise, research, and review of customer-submitted data to define the scope and identify customer expectations, use that information to plan what to write, how much to write, and where to place it.

For example, identify the type of content to write based on the feature:

An interactive workflow to create and assign tickets to specific users might require you to write a task, a use case, and requirements.
The new dashboard widget might require you to write a task for how to add the widget, a reference for the available widget settings, and an example use case for the widget.
A new SQL function might require you to write a reference topic about the arguments and output, as well as several examples of the function in use.

For the content to be findable, you must identify where people (and AI agents) might look for information about the functionality. For example:

Content about an interactive workflow to create and assign tickets to specific users might be placed by existing triage and assign workflows, or organized with other content targeting the same audience.
Content about a new type of widget that can be added to a dashboard might be placed by other widget docs and added to a parent reference list of available widgets.
A new SQL function might be placed with similar types of functions, or even organized with the name of a competitor’s SQL function as an alias in the navigation to improve findability.

To take a data-informed approach, you can use the following data sources to plan how to structure the content and where to place the content:

Expertise

Business understanding

Research

Product exploration
Documentation exploration
Competitive analysis

Customer submissions

Search terms
AI chatbot conversations
Feature requests
Community forum

System

Documentation metadata

Most of these data sources are qualitative. Because you’re writing something new, you want to identify existing patterns and mental models that might exist in the industry, but otherwise you’re largely relying on your expertise and understanding of the customer and business, plus research about the existing documentation content and new product feature when deciding where to place the new content.

You don’t need to use all of these sources to help inform your key content decisions. Use the approach that makes sense, given what you can do easily, quickly, or effectively based on your available tooling and analytics capacity.

For example, to guide the following key content decisions as you define your plan of what to write, you can use the following data sources and analysis questions:

Key content decisions	Questions to ask of the data	Data source
What should I name the topics? What keywords should I mention in the opening of the topics?	What terms do customers use today when looking for information about this? Are there unsuccessful searches for this concept already?	Search terms
How should I frame the topic? What keywords should I mention throughout the topic? What terms should I make sure to use consistently? What use cases should I use for examples? What mental models should I make more explicit?	What questions do people ask of an AI chatbot? What terms do they use when looking for information about the subject that you’re documenting? Are there questions with made up responses in the AI chatbot conversation data?	AI chatbot conversations
What use cases should I use for examples?	Have customers asked for this functionality? What reasoning do they provide?	Feature requests
What other features should I mention to disambiguate the jobs-to-be-done for the feature?	What use cases are customers trying to accomplish already that this feature could address?	Community forum
What information should I include in the introduction? What use cases should I use for examples?	Why is this feature being built? Why now? What gap in the market does this feature fill?	Business understanding
How should I structure my content? What terms should I use in my content to improve findability	What content do competitors have about similar functionality? What information do they provide?	Competitive analysis

Your documentation explorations can help you understand how and whether similar, but different, functionality is documented for your customers. That research can guide how much content design work you need to do in deciding how to document the new dashboard widget, as well as identifying what patterns your customers might expect from your dashboard documentation content.

To help identify where to place the new page in the navigation and information architecture, answer the following questions:

How is the company positioning the new feature or functionality? Is there similar or existing functionality that is positioned in the same category?
What sections exist in your information architecture today? What architectures are possible with your tooling?
Where do competitors place documentation about similar functionality, if it exists?

To help you assess page structure, answer the following questions:

Where do people searching for information about this functionality end up today? What terms do they use?
How long are the existing pages about a feature? Consider using page length as one indicator to help you decide whether to write a new page or update existing ones, in addition to content type.

At this point in your medium-sized documentation project, you have a detailed plan outlining customer expectations, project scope, and a sense for what content to write, how to structure it, and where to place it.

Your next step is to write the content.

Write a medium-sized documentation project

The writing process is where you focus on delivering on your data-informed plan — both writing the content itself and placing it in the designed structure. Planning and writing are intertwined, so as you continue using the product to draft your task, you continue reevaluating the scope and updating your plan for what to write and how.

For example, start drafting a task outlining how to add the widget to a dashboard, featuring an example that combines with widget with another widget type, as well as a reference topic outlining the formatting options available for the widget. As you build an example dashboard to support your content about the new widget type, you might discover a missing setting that won’t be added in time for the release, so you write a note about it, updating your plan and your content in tandem.

Before AI-enabled writing workflows were common, writing was the stage where using data to inform your process was the least relevant, but that’s no longer true. If you draft content with AI agents in the loop, you can use the data from your planning stage as part of the context that you provide when creating a draft. For example, provide the specific use cases that the widget was designed to support, the terms used by customers and internal folks when describing the functionality, as well as references to existing similar pages to align structure and style of the content with existing dashboard widget task and reference pages.

If you don’t use AI in your writing workflow, you can still use the data sources and metrics that you reviewed during the planning process to inform your writing process, especially to validate assumptions about the right approach to take during the writing process:

As you write examples, consider the customer use cases to assess the relevance of the examples.
As you write headers, titles, and introductions for pages, review the customer search terms and keywords used internally to describe the feature to evaluate the discoverability of the content and the consistency of your language.
As you structure the content, evaluate if you’re matching the format of existing similar content types, or intentionally deviating.

Decide whether to add screenshots

When you plan new content, you can use data to help you decide: Should you add screenshots to documentation?

Screenshots are most helpful when they are relevant to the readers and useful for the context of the documentation. How do you evaluate that? With data!

For example, when adding documentation about a new dashboard widget that animates images in a repeating pattern:

Use on audience research:

Is this widget concept totally new to them?
Do they know how dashboard widgets generally work?
Are they familiar with a different configuration UI for widgets?

Use product and documentation research:

Is the widget setup design confusing?
Are you providing a reference, task, or example topic?
What is the goal and learning objectives of the topic?
Do similar topics have screenshots?

Use your business understanding:

What resources exist to help you maintain the screenshots?
Can you automate the screenshots with the tools available to you?

In this case, you might recognize that a new dashboard widget that animates images in a repeating pattern is a new concept for many readers, so adding a screenshot of how the widget looks when fully configured to the task documentation to illustrate an example can help support the business value of the feature.

If you have a higher analytics capacity, you can use additional data sources to validate the decision to add one screenshot.

Review page quality feedback for dashboard widgets:

Are people requesting more screenshots?
Do topics with screenshots get more or less page quality feedback?

Review website analytics for dashboard widget pages:

Compare the page views and referrer traffic for a high quality dashboard widget topic with screenshots to one without screenshots.
Compare the click activity on the similar pages, do users click or hover over the screenshots on the page with screenshots?

With a data-informed understanding of the product, your audience, your business capabilities, and current user activity, you can make a sustainable decision about screenshots.

You’ll likely redo some product research as part of the writing and revision process, because the product has likely changed since you started planning and writing. For example, check the product to validate the accuracy of your documentation draft, ensuring that you reference accurate UI strings and navigation paths, as well as relevant option and parameter names for API workflows.

After you write, revise, and publish your medium-sized documentation project, it’s time to evaluate it.

Evaluate medium-sized documentation changes

Were the docs useful to your customers? Are they accessing the docs? Are they asking questions answered in them and are the docs helping to answer? These are key questions to consider when evaluating medium-sized documentation changes.

When you add content about a new feature, there isn’t a baseline to compare against, but you can still evaluate what you produced.

First identify if you hit the most basic goal of delivering self-service support that is clear, useful, and relevant to your users.

One good signal can be the volume of internal questions. Oftentimes, the first readers of documentation about a new feature are the sales and support folks that are trying to understand it on behalf of customers that they’re helping, or prospects that they’re pitching. If you don’t see that many questions, or if the vast majority of questions can be easily answered with a link to the documentation, that’s a good initial signal that your documentation is useful and relevant.

However, the internal customers are not your primary audience, so you also want to evaluate more customer-specific metrics.

Short-term evaluation

In the short term after the release, monitor support cases and chat volume, product bugs and GitHub issue reports, and search queries to identify missed opportunities in the content or validate successes. Medium-sized documentation changes, or any changes to support a new feature, are perhaps the only changes for which you can do some preliminary evaluation immediately after a release.

What you can evaluate, how effectively, easily, and coherently, depends on your analytics capacity. The higher your capacity, the easier it is to evaluate quantitative metrics like feature adoption, documentation page views, and support case volume together on a graph and evaluate correlations against baseline usage. If you have a lower analytics capacity, you might not have a quantitative baseline, or one that you can make much sense of to help you evaluate this medium-sized change. In that case, you can use a more qualitative approach to evaluating your success in the short term.

Correlate quantitative metrics

After a release, you’re likely to see different post-release correlations across those three quantitative metrics:

Product telemetry
Support case volume
Website analytics

For example, for a new dashboard widget that animates images in a repeating pattern, if a lot of customers were waiting for it and closely followed the release notes, you might see both feature usage and documentation page views for the new pages increase after the release, such as in charts A, B, or C.

If the release was not hotly anticipated or perhaps is for a feature that was already broadly available and just reaching general availability, you might see a pattern like chart D in a short term evaluation. Compared to the product usage metrics generally, feature usage didn’t increase — not much has changed compared to before the release.

For a feature with immediate adoption, you can evaluate the short term success of your documentation by assessing the trend of the documentation usage and support case volume for pages and cases related to the new feature.

For chart A, assuming a feature going from private preview to public preview, people are using both the newly public feature and its documentation, but still confused enough to contact support with roughly the same relative frequency as when the feature was available only to select customers privately.

For chart B, people are using the feature and its documentation, but a brief dropoff in feature usage could indicate a lack of success with the feature. The continued documentation and support usage likely indicate confusion with the feature that probably isn’t fully resolved by the documentation. If the dropoff was due to a seasonal holiday, you’d expect to see usage of all three metrics go down at the same time, which is why it’s important to review the metrics together.

For chart C, the usage is a bit noisier in the data, but it’s generally a good signal for product usage and documentation usage to go up while support cases either stay flat or go down, indicating that folks are using the product generally successfully with help from the documentation as needed, without needing to contact support for much help. You can also perform a spot review of support cases before the feature was widely available and after, to determine whether the higher volume was customers asking about the availability of the feature or asking for help with it.

I recommend looking at all three metrics together. If you look only at documentation page views (as a way to proxy usage of the documentation pages that you added) you might draw misguided conclusions about the documentation usage.

For example, if your new dashboard widget documentation has very few page views, you might think it’s not useful. But if feature usage for the new widget is also very low, that indicates that the low documentation usage is likely unrelated to your content.

Instead, something else could be happening. If the feature wasn’t announced, or doesn’t address a gap in the product felt by a large segment of the product audience, product adoption might be slow. Discoverability of the feature itself influences interactions with your documentation, especially in the short term.

If the only data you have access to is documentation page view data, you can reliably use it to evaluate awareness of the feature, but not usage or success.

Even if you don’t have only sparse and statistically insignificant quantitative data, it can still be useful for decision-making and informing your documentation practice. Bob Watson elaborates in his post: If it’s not statistically significant, is it useful?.

Consider qualitative sources

Beyond correlating three quantitative metrics together, you can assess more qualitative data sources to attempt to extract more intent-rich insights. For example:

Customer submissions

Support cases
Product bugs
GitHub issues and PRs
AI chatbot conversations
Search terms

You don’t need to review every data source in this list, and you don’t need to review all content from each source. Reviewing a sample of just one qualitative source, especially if you have a basic or growing analytics capacity, can give you some useful information.

Data source	What to look for in the short term
Support cases	Do you get cases confused about the new feature, or with questions not addressed by the documentation? Is there a pattern to the questions? Are the questions about the feature more complex than before, indicating that perhaps more basic questions have been addressed by your documentation?
GitHub issues and pull requests	Do people open issues asking about functionality supported by the feature? Are there problems with its functionality for some customer deployments?
AI chatbot conversations	Are relevant questions being answered more accurately? How are the evaluation scores for the new content?
Product bugs	Are there any bugs with the feature discovered by customers or QA after the feature launched? Do any of them necessitate documentation updates? (Like a limitation that was missing from the docs)
Search terms	Do search terms about the issue find results? Are there fewer unsuccessful searches? Do you have a higher % of clicks on the page that you updated? Is search volume higher?

GitHub issues, and especially pull requests from contributors, can be an indication of product usage even if you don’t collect or have access to product telemetry. However, there is a risk of relying on those as a signal without correlation from other channels of data. People file issues and contribute pull requests for functionality that they’re using and want to improve — but a lack of issues doesn’t mean a lack of usage for a product feature — it might be frequently used but satisfactory in its current state.

Another assumption to avoid when analyzing product telemetry data (either directly or implicitly through product bugs and GitHub issues) is assuming that current and past usage patterns are indicative of future usage patterns by a customer. A customer testing and planning to roll out the new functionality to their user base looks different in the usage patterns than a fully scaled production workflow.

To mitigate these risks, correlate any decisions or conclusions drawn from product telemetry alone with user research, either by talking directly to customers using the capability, or at least the internal stakeholders that work directly with those customers, such as Customer Success Managers or Professional Services teams.

In some cases, you might want to perform a longer-term evaluation of the content you added for your medium-sized project.

Longer-term evaluation

If your product customer base is largely enterprise-sized organizations with slower adoption curves, or you’re attempting to assess documentation that supported a relatively low-key unannounced feature, a longer-term evaluation is more useful than a short-term data check.

In these cases, you can use the time immediately after the release as a pseudo-baseline, and correlate product telemetry for the feature with documentation usage to evaluate any patterns .

Data source	What to look for in the longer term
Website analytics	The page views and click interactions with the page, such as clicks on code samples or clicks to highlight text, increase. User sessions and referrer traffic indicate that the journeys to get to relevant information (the pages you created or updated) are shorter.
Product telemetry	Evaluate documentation usage with product adoption data to determine if there is a correlation.

For example, for readers using search or other pages to access information in your documentation, their paths might go from messy and convoluted session activity patterns:

To a more streamlined and simple approach where they land directly on a relevant page:

Interpreting session length depends on topic type

A shorter session length makes sense only in context of the documentation content.

A short web browsing session on the documentation site could mean any of the following:

Someone got frustrated and left without finding the answer they sought.
Someone found what they needed quickly and left to return to their task.
Someone was mid-exploration and they got interrupted by a surprise software update restarting their computer.

When attempting to interpret user session activity, compare a specific session against a baseline session length for similar topic types and audiences.

Someone with a long documentation session, visiting conceptual pages, reference pages, and task pages in the same session might be frustrated trying to find a specific piece of information, or they might be learning and trying to understand the feature before they start using it.

For example, if the topics are all about configuring authentication and provisioning new users, the session might be more likely to represent a thorough reader when compared to a similar session journey through dashboard documentation — but it might not be! Quantitative data cannot encode intent, only activity and volume.

Evaluate different pages differently

If, due to your analytics capacity , you rely primarily on page view analytics to evaluate your medium-sized documentation changes, you must evaluate different page types differently. You cannot derive one single metric to define the success of every documentation page that you publish. Instead, you can evaluate specific pages.

If you don’t know what the goal of a specific page is, you cannot evaluate its success.

Page	Goal	Measurement
Documentation homepage	Attract customers from search results Direct customers to other pages	Track sessions started from organic traffic Track on-page click volume and targets
Task (How to do X, Create and manage Y)	Help customers accomplish a task Provide instructions	Track support case volume Track search term volume landing on this page
Landing page	Provide a conceptual overview of content Direct customers to other relevant pages	Track page views with this page as a referrer Track page rank in search results for generic search terms about the topic
API or code reference	Help customers write code	Track clicks to copy code examples Track successful endpoint requests performed on the documentation page.

There are some universal data signals for documentation pages, but they require additional time-consuming analysis to be reliable, such as:

Tracking MCP server interactions that return the page, which requires validating the accuracy of the response to validate usefulness.
Tracking AI chatbot conversations that reference the page as a source, which also requires validating the accuracy of the response to validate usefulness.
Tracking page quality feedback on the page, which is a low-volume self-selecting signal that isn’t representative of all users.

The goal of evaluating your changes over the short term and long term is to evaluate the success of your content decisions. Keep track of what worked for a specific project, note what you might want to repeat, and share it with your colleagues.

Use data to inform a medium-sized documentation project

When you use data to inform a medium-sized documentation project, you can more effectively plan the scope of the work and design the content required. As you write and review the content, you can make decisions, iterate on the plan, and add context to AI-powered tools. When you attempt to evaluate the success of your project, the data you gather and analyze can validate the usefulness of your approach.

Inform a large documentation project with data

Tue, 27 Oct 2026 10:30:00 +0000

If you’re about to start a large documentation project, you can inform each step of the process with data. Why? So that you can be more confident in the decisions that you make, and to base those decisions in what customers are actually doing and asking about.

In the context of this post, a large documentation project is something like reorganizing a large set of existing documentation, or writing a large set of documentation from scratch to support a new feature.

Maybe a longstanding bit of functionality is being deprecated and replaced with another set of functionality
Maybe a new feature launch means that you need to reorganize and reframe an existing set of content.
Maybe a large change to the user interface is launching, requiring some new documentation and a lot of updates to existing content.

No matter the specifics, a large documentation project is one that will take you a few weeks or months to complete. A large part of that time is likely to be spent in planning — identifying the scope, direction, and desired output of the project.

In this post, I’ll cover how to use data to inform each phase of the project:

Plan your large documentation project

When you plan a large documentation project, you primarily want to identify the scope and the direction of the project itself, answering questions like:

What documentation pages are affected?
What changes need to be made?
How much work will the changes require?

Answering these questions can be easier when you add data.

Expertise

Business understanding
Documentation understanding

Research

Product exploration
Competitive analysis

System

Documentation contents
Documentation metadata

Customer submissions

Search terms
Website analytics
Community forum questions
MCP server interactions
AI chatbot conversations
GitHub issues and PRs

Even if your organization has a relatively basic or growing analytics capacity, planning a large documentation project can be a good place to start practicing data-informed documentation if you have the time and support. While your organization might have some gaps in existing data sources or expertise, you can start to build capacity with targeted data gathering through a content audit or documentation metadata collection.

Consider what you already know

A perhaps under-considered data source when planning a documentation project is your own knowledge It might be nontraditional to consider subjective information (your own personal expertise) as a type of data (it has been pre-processed and transformed into knowledge, so it isn’t data in its raw form!), but your personal expertise is essential context, and a crucial component of any documentation planning exercise. .

Each documentation project exists because something in the organization created a need for it.

Your personal context and understanding of the organization is essential to help plan and scope the documentation project itself. Depending on your tenure at an organization, you might apply this context subconsciously, but consider making it an active, intentional part of your planning process.

Especially if you use AI agents to plan your work, an agent does not have access to your own expertise unless you provide it as part of the context.

The data source of your understanding of the business is also possible to access for anyone, no matter their analytics capacity. Recognize your place in the organization and review what you know.

Take an example project where new functionality is being released, and you need to reorganize and reframe a large, existing set of content. Your knowledge about the organization can contribute to planning a large documentation project by answering the following questions:

How will the new functionality be positioned in the market?
Does the new functionality target a different buyer than the existing product functionality? If yes, who are they?
Is the new functionality a central part of product market positioning, or is something else the focus?
What company strategic initiatives does the new functionality support?

You might end up doing some research , or building some partnerships with folks in marketing, to more fully collect answers to these questions.

Why are these questions relevant to consider when planning a large documentation project? The answers can help you address scoping questions like:

Does the documentation architecture need to be updated to reflect changes to product positioning in the market?
What use cases might you want to address directly with examples?
Will specific kinds of decision support or conceptual overviews help support sales enablement or product marketing collateral?

In addition to compiling data from your knowledge about the company and product positioning, perform some focused research.

Perform research

Research is another form of data collection and analysis . Identifying what you need to know in order to effectively plan the shape of your content involves research into product capabilities and context about the way the product development process functions.

For a large project especially, it’s valuable to review what industry leaders and competitors document for similar large projects.

Do product research

To effectively plan documentation about a product, you need to know about the product. As part of the research you perform , gather data about the product development pace, patterns, and plans:

Is this functionality going to stay the same for several years, or will it change again in a few weeks or months?
How much development is going on in this feature area, now and in the future?
What future projects are planned in this feature area?
Is this a generally available release, or an alpha, beta, or preview release?

As part of your job you might have enough relevant product expertise to start planning the project already, but you might also need to do dedicated research to collect relevant data.

Do focused research to answer product-specific questions like the following:

Is this feature or functionality similar to existing functionality in the product? If so, how is it similar? How is it different?
How discoverable is this functionality in the UI? Does it have a top-level menu or is it buried several layers deep in a menu, behind an unlabeled icon, or something else?
How many changes are being made to the user interface?
Are there new permissions requirements being added as part of this project?
How confusing is the UI to use? Will it stay that way?

Overall, to help you plan you want to know: What is changing? How much is it changing?

As part of your research, use the product yourself! If possible, access a development or staging version of the product functionality and use it as a user might to perform specific tasks.

If, due to the type of product that you’re developing (or other reasons), you can’t directly access the product to explore it yourself, you can still use other research methods to answer these questions:

Interview the developers and designers that contributed to the product changes.
Review pull request descriptions, screenshots, and work-tracking tickets from a system like Jira or Linear.
Read the code, possibly with assistance from an AI agent prompted to gather data, to help answer relevant questions like required permissions, scope of the changes to the user interface, and more.

You can then use the data that you collect to scope the large documentation project. For example, given a large scale deprecation, a new feature launch, or a redesign of the user interface, consider the following:

Does I need to add new standalone pages for the new feature launch, or will I mostly be updating existing pages?
How many existing pages might I need to update?
Do I need to add a conceptual overview about the redesigned user interface?
If the new feature is similar to an existing feature, do I need to add decision support guiding users about when to use one or the other?
Especially if the user experience is confusing or the new functionality is hard to find, how much detailed content is relevant for me to add?
How many screenshots do I want to add to support the redesigned user interface?
Is a tutorial relevant and useful for users, or would an end-to-end example be more clear?

For example, if you are documenting new functionality that is incredibly complex and buried several layers deep in a menu when you test it out, you can give feedback to the product engineering team that they might want to update it, but you might also plan your documentation deliverables differently, perhaps planning to add more screenshots to your task steps or more detailed wayfinding guidance in introductory pages.

Perform competitive analysis

For some large documentation projects, it can be useful to perform a competitive analysis or review of competitor documentation and websites. Gather data from the broader industry and how your documentation exists in that context :

What are your competitors doing with their documentation?
What content structures are in use elsewhere?
What terms are commonly in use to describe different features or functionality?
What types of content exist for this type of feature in similar products?

For example, given a large scale deprecation, or a redesign of the user interface, you might review the content of industry leaders for best practices to use as models for your own content:

What content types support a large scale deprecation or redesign?
How do other organizations communicate deprecation timelines?
What do you like or not like about the choices others are making in communicating the changes?

For a large documentation project supporting a new feature launch or a new product line, you might review competitors with similar features or products:

What content types exist?
What sections exist and how are they organized?
What terms do those organizations use to name the feature or product capabilities?
What use cases and examples are referenced as supporting content?
What do you like or not like about the architectural decisions?
How do the architecture choices align with (or not) the current state of your organization’s documentation?

You can use the competitive review and analysis to plan the shape of the work that you want to produce for your own large-scale documentation project:

What does the ideal end state of this content look like?
Is aligning terminology going to be part of the project?
What content types need to be included for this type of documentation?

Documentation-specific data

Data about your organization’s existing documentation is crucial to inform scoping questions for the planning process.

Documentation-specific data is the broadest category of data, and also accessible in different ways to organizations with different analytics capacities . If you have a lower analytics capacity, you might only be able to perform basic tasks from this section, possibly a content audit or some small-scale tooling assessments. If you have a defined or mature analytics capacity, you can likely take advantage of most of the guidance in this section.

To help you plan your large-scale project, take advantage of the following documentation-specific data sources:

Assess the current state of your documentation team, processes, and tooling.
Collect data about the current state of your documentation with a content audit.
Review metrics and metadata to inform and prioritize the changes in your plan.

Assess your documentation understanding

To help plan what resources are available to you as part of the large project, collect answers to the following questions about your documentation team:

How many people are working on related projects?
Who might have additional bandwidth available?
Who has different helpful skills that might help make the project more successful, like a background in instructional design, visual design, or video production?
Is translation or localization of content a consideration?

To help plan what content shapes, structures, and tactics are available for your large documentation project, collect answers to the following questions about your tooling:

Is content reuse supported?
Are there platform limitations for different types of information hierarchies?
Can you programmatically update screenshots or text across multiple pages of content at once?
Can you use AI tooling with the content management system?
Do you use version control systems to track changes over time?

The answers to those questions can help you plan the project:

Identify the need for a release branch strategy in git to streamline collaboration of multiple writers on related content.
Determine the amount of work necessary to complete and whether additional writers or other collaborators are necessary to finish the project during the available time.
Recognize tasks that might take more or less time depending on the limitations of the content management system.
Identify limitations in tooling that you need to plan around in advance, such as navigation structure limitations.
Plan where to draft the long-lived content for the large-scale project.
Account for expected time to complete translations to make localized content available.

With an understanding of the current state of your documentation site, tooling, and content, you can plan the scope of the project more accurately, considering issues like:

What content structures and designs are possible? How can I structure the end result?
Will this project affect the translated docs?
If yes, do I need to finish my documentation sooner so that it can be translated in time for the release?
Where do I place the content in the table of contents for the site?
How many other writers or teams do I need to coordinate this project with?

Perform a content audit

A content audit is essentially a targeted data collection exercise, reviewing the current state of the documentation . Often, a content audit is performed as a quality evaluation of an entire set of content. However, for a content audit to support planning a large documentation project, you can scope it to just the relevant sections of the site.

For example, if you are planning documentation to support a product deprecation, you need to perform a content audit of all the pages that mention that product (which is hopefully not every page in your company’s documentation).

A content audit is important data collection. With a good understanding of the current state of the relevant parts of your documentation, you can more accurately plan the scope of the changes you need to make as part of your project.

As part of the audit, answer questions like the following for each page:

How accurate is the content?
How complex is the page structure?
Who is the audience?
What is the goal or learning objective of the content?
Is the content up to current style guidelines?

Depending on how much time you have available to perform an audit, you can provide in-depth answers or perform surface-level evaluations.

For the example of a deprecated feature, a content audit might help you recognize the following about the affected documentation pages:

Most pages are accurate, but some are inaccurate and will need additional updates as part of the deprecation work.
Some pages are structured with a lot of complex tasks, so those pages will need to be restructured and rewritten to make it easier to communicate the deprecation, for example by separating the tasks specific to the deprecated functionality to a dedicated section, instead of being integrated with the page sections.

The content audit produces data you can use to consider the scope and shape of the plan for your large documentation project.

Review documentation metadata

Documentation metadata can help you scope the project as well. You can gather and analyze documentation metadata like the following :

Metadata	Example value	Source	Level
Page count	`812`	Content management system	Site
Section title	`Administer`	CMS	Page
Last updated date	`2026-08-23T16:04:34Z`	Version control or CMS	Page
Header count	`8`	Computed	Page
Header depth	`3`	Computed	Page, per header
Link count	`4`	Computed	Page
Unique link count	`3`	Computed	Page
Image count	`1`	Computed	Page
Image has alt text	`True`	Computed	Page, per image
Word count	`1273`	Computed	Page
Code sample count	`4`	Computed	Page
Code language	`Python`	Computed	Page, per code sample
Code test results	`Pass`	Test suite	Page, per code sample

You can gather this data through a manual content audit, through an API, or compute it yourself based on the contents of your documentation pages with a script. Some metadata might be available in the files containing your content, such as in page frontmatter. Other metadata might be site-specific and configure the navigation or table of contents of your site. Other metadata might be available from a version control system, like git. Other metadata might need to be computed.

The approach you might take to collect documentation metadata depends on the tooling that you use and your analytics capacity. The more API-accessible your tooling and the greater your analytics capacity, the more likely you can perform a complex, scripted collection & analysis of this metadata. With a more basic analytics capacity, you’re likely counting screenshots by hand and inputting data into a spreadsheet Speaking from experience… .

Version-control-specific metadata

If you use version control, you might also have access to git commit metadata, for example the details of a pull request squash-merged to your release branch in GitHub.

Version control systems can also usually show you a line-by-line difference of when a page was last updated, making it easier to see precisely when an image was last updated, for example. Alternatively, if you host your own images, you can use the last updated date for the image file itself as a signal.

The data that you collect might be well-structured like the following, or it might be a chaotic spreadsheet. Either way, it can be useful metadata for planning a large-scale documentation project.

Example JSON-formatted documentation metadata

{  
  "section": {
    "title": "string",
    "pages": 
        {"pageId": {  
            "title": "string",  
            "url": "string",  
            "last_updated": "datetime",  
            "contents": {
                "body":"string",
                "word_count":"number",
                "headers": {
                    "total_count": "number",
                    "header": {
                        "depth": "number",
                        "text": "string"
                    }
                },
                "links": {
                    "total_count": "number",
                    "link": {
                        "path":"string",
                        "external":"boolean"
                    }
                },
                "code_samples": {
                    "total_count":"number",
                    "code": {
                        "sample":"string",
                        "language":"string",
                        "test_results": "boolean"
                    }
                },
                "images": {
                    "total_count": "number",
                    "image": {
                        "path":"string",
                        "alt":"string",
                        "last_updated_date":"datetime"
                    }
                }
            }
        },
        "pageId": {  
            "title": "string",  
            "url": "string",  
            "last_updated": "datetime",  
            "contents": {...}
        }
      }
   }
}

With whatever metadata you have available, you can answer at least some questions like the following:

Question	Metadata
How many pages are there?	`page_count`
How many pages in each section?	`section_title`
When was each page last updated?	`last_updated_date`
How many headers exist?	`header_count`
What depth are the headers?	`header_num`
How many links exist?	`link_count`
To which pages do the links point?	`link_count_distinct`
How many screenshots and images exist?	`image_count`
Do the screenshots and images have alt text?	`image_alt_text`
Are the screenshots and images up-to-date?	`last_updated_date`
Are there code examples on the page?	`page_code_fence_count`
Does the code run?	`code_test_results`

The answers to these questions, in combination with other, more targeted data collection like the content audit or competitive analysis results, help scope and outline the shape of your large project.

For example, given a large scale deprecation, a new feature launch, or a redesign of the user interface, consider the following to scope your project:

How many pages have images that might need to be updated or removed entirely?
How many pages include content about the deprecated functionality? How many include UI-based steps that will be changing?
How many links do you need to update?
When might you want to update existing new pages or add new pages because the current ones are too long or complex?
How many pages will need general accuracy updates or rewrites when they’re updated for this project?

The metadata by itself doesn’t offer enough context to help scope the project, but when combined with your documentation research and product research, you can plan the shape of the large-scale project.

Examine customer data

When planning a large scale documentation project, customer data can be a valuable source when making more tactical plans about what content to write and how to write it. To plan the specifics of what you will write, you can gather data sources like the following:

Search terms
Website traffic, referrer data, and other analytics
Community forum questions
MCP server interactions
AI chatbot conversations
GitHub issues and PRs

Depending on your analytics capacity, this data might be available to you in a boilerplate analytics tool like Google Analytics, a dashboard in your content management, a dedicated data analytics tool like Snowflake, Sigma, Tableau, or others. You might also not have access to any of this data.

You can use the data sources available to you to answer specific questions like:

Do the search terms used by customers match the terms used in the documentation?
Which keywords commonly lead people to the documentation that you’re updating?
Do people ask about this functionality when interacting on the community forum or with an AI chatbot?
What use cases and challenges do people talk about on the community forum or with an AI chatbot in context of this functionality?
Which websites and content types refer people to the documentation?
How many unique viewers and views does each page have?
Which agent-derived keywords through MCP server interactions generate traffic to the pages in your documentation that you plan to update?

The answers to those questions then inform your plan for the large-scale documentation project:

Inform what terms to include in the topics that you plan to write, such as guiding title or header terminology choices.
Guide which content to move or not move, based on referral traffic or organic search traffic that might make a URL slug change expensive.
Identify pages with strong, existing information scent (popular search destinations) that might need special handling to make sure you don’t affect existing content findability.
Prioritize specific use cases or examples to implement in the content.

Each data trail is a trace left by a user that you can use to derive vague usage patterns that you can model and shape as you redesign the content experience with your own updates and changes as part of the large documentation project.

Plan the shape of the work

As you collect and analyze relevant data sources, you can plan the shape of the large documentation project and the end state that you are working toward.

With the competitive analysis, you identified different content types to write and navigation structures to implement.
As part of the content audit and documentation metadata review, and assessing the documentation-specific data you identified the scope of the pages affected, constraints and opportunities from the team and tooling, and types of changes that need to be made.
You reviewed customer data and activity to guide content decisions.

When you know the shape of the work, you can identify what success looks like so that you can evaluate it later. For example, for a deprecation, success might be an easy reference page to send in an email about the deprecation; for a UI redesign, success might be fewer questions than expected about the UI changes in support chats. Take a moment to define a measure of success as part of your plan.

Write a large documentation project (informed by data)

Writing is the stage where using data to inform your process is perhaps the least relevant. You’ve already made a data-informed plan — this step is about delivery. Enter that fugue state and get to writing.

For example, given a large scale deprecation, a new feature launch, or a redesign of the user interface, this is when you start making the changes:

Surgical updates to pages that link to others to mention deprecated functionality
Sweeping changes to task steps to change the navigation instructions
Scaffolds of a new section of the navigation and accompanying new pages to match
Meticulous updates to screenshots

As you start drafting and reviewing, you might discover new data that requires additional planning — some previously unidentified scope of the project, or new user requirements that involve updating additional pages and more product research. Writing and planning can be an iterative process, especially for a large project that runs over many weeks.

But keep the data that you collected as part of the planning process close at hand. There are still some opportunities to use that data to inform your writing tasks in a large documentation project.

Guide AI-driven prompts

If you use AI tools as part of your drafting process, whether to draft content, make larger mechanical changes like link slug updates, or create new files that you then author, the data sources that you used as part of planning can be valuable context to guide AI-driven prompts.

Use search terms as context for header, introduction, and page title drafting.
Use existing, up-to-date pages as reference models for new file creation.
Use curated community forum questions, AI chatbot conversations, and GitHub issues as fodder to create a troubleshooting guide.
Include product-positioning context and audience details to output relevant code examples based on actual customer use cases.

If your data sources are available with an MCP server, it’s even easier to add relevant context to your drafting, for example with a prompt like:

Use the MCP server to look up support chats that mention an error or bug from the last 60 days and identify the related features. For issues related to the to-be-deprecated functionality, propose troubleshooting sections in order of frequency based on the findings.

Or for automating content updates related to the UI redesign:

Follow the pattern established on this reference page /path/to/human-authored-draft.md to update the other pages in the same section. For guidance about terminology, use the MCP server to look up the terminology list.

If you don’t use AI tools as part of drafting, but you do use AI tools as part of the content review process, you can follow a similar prompt for the deprecated functionality example:

The following pages are new and address the same use case as the to-be-deprecated functionality on these other 3 pages. Review the headers and introductory sentences for each new section for consistency with the search terms that lead users to click on the 3 preexisting pages.

Data is context for AI tools, and the output can be improved with relevant, curated context for your task.

Whenever you plan to use AI with documentation drafting, make sure that you have an established AI strategy for documentation to help ensure responsible, relevant, and accurate usage.

Inform tactical choices

You can also use data to inform tactical choices throughout the writing process. As you draft content, you might encounter judgment calls like how to phrase a heading or whether to put content on a new page or leave it where it is. In those cases, review the data you collected during the planning process to validate your assumptions about the right approach to take.

Decide what to name a feature

For a specific task like determining what to name a feature, it’s straightforward to use data to inform your decision.

Start by gathering information about existing terms. Which terms are in use, how are they used, and how common are they in the industry? Review sources like:

Competitor documentation, blogs, and websites
Google ngram and Google Trends
Documentation site search terms
Google Search keywords leading to the documentation and company websites
AI agent conversations

After reviewing the data, you can make a decision (or a recommendation, if you don’t have decision-making power).

If you get pushback, you can share the data that you used as backup for your decision. A discussion is also another opportunity to gather data — maybe you’re missing some context about product positioning, business direction, or lack access to a data source that offers a compelling counterargument.

Data is not an impenetrable backstop. Be curious, not defensive, and build connections to gather information and context that can help you do your job better — and help the user succeed with your product.

Other tactical choices that you can inform with data are the readiness to deploy your changes. As part of your plan, you likely prioritized high-value pages to update based on usage. As you continue to write, you can evaluate the progress against your plan and your knowledge of the product development and release process to identify when your work is “done enough” to release.

Advise review decisions

As you finish the drafting process, data also informs how and when you might send out your draft content for review.

Based on your understanding of the organization and product priorities , you might know that content related to this project is high priority and iterative review cycles with smaller drafts will be easier for folks to review (show that you are doing something), rather than one final dedicated review process that takes multiple weeks with fully drafted content.

Data about your output can also help here — consider how many pages you updated, which ones you’re more or less confident about based on your product research , and the different projects taking time from your technical reviewers — to prioritize what content to send for review when.

You can also use data to assist with the actual review process itself, using a style linter like Vale to collect data about the adherence of your content updates with the style guide rules of your documentation site and validate consistency in terminology.

Evaluate large documentation changes

After you publish your large-scale documentation changes, you’ll certainly let out a big sigh of relief. While documentation updates are never completely done, after you release a large set of changes you can evaluate the results.

As part of your plan, you might have defined what success looks like. With a complex and large project, it can be difficult to measure the effectiveness of the changes if you don’t know what the goals of your content, and the project, are. For example:

For the UI redesign, measure support chat volume.
For the deprecated functionality, measure referrer traffic.
For the new feature, measure user engagement.
For the reorganized content, measure discoverability improvements

For many changes to existing content, you want to wait several months and compare user activity against a baseline set from before the change, either from the same time of year or not, depending on how much your content and metrics have changed.

Part of the reason for this is that it takes user behavior several months to adjust to change. Especially for evaluating changes that are not tied to a specific date or customer communication, a longer, baseline-driven analysis is more valuable for evaluation than checking analytics a week after the release and using that as your only evaluation metric.

For guidance on how to determine a baseline, refer to the informative posts from Bob Watson, How you can make sense of your site analytics, and You’ve tamed your analytics! Now what?.

The less analytics capacity you have, the less likely you can rely on baseline data (like comparing before and after changes in data points), but you can still perform pointed data collection to evaluate the effectiveness of your content.

If you don’t see any difference in any of your success measures even after a few months, you could wait a little longer, turn to qualitative data sources like UX research to try to get more feedback, or consider whether your success measures are flawed and consider other metrics to review.

Evaluate support chat volume

For the UI redesign, maybe you hope that less than 5% of support cases are navigation questions related to confusion with the new UI.

Customer submissions:

Fewer support cases about the navigation questions, and those that do happen include links to the documentation as reference to help assist the customer.
More clicked results in the search terms leading to the page about the changed navigation and fewer unsuccessful searches.

One risk of this success metric is that the support team didn’t know about your documentation, and perhaps your documentation introducing folks to the redesigned UI (compared with the previous UI) was not included with the communications sent to customers. So even if support chats are down, your page views might be low and very few support chats actually link to your documentation.

However, you can mitigate this risk. This sort of pattern in the data can be a reminder that often, publishing the documentation isn’t enough. You also need to evangelize the existence of the content internally, and perhaps externally as well. Build partnerships with colleagues in support, customer communications, sales enablement, customer success, and marketing. Help ensure that blog posts about the changes, email communications about the changes, and internal messages about the changes all include reference to your content as the authoritative customer resource.

Another risk about this success metric is that it assumes that one canonical page is responsible for customer success with the new redesign (one explaining the before and after changes), and doesn’t consider the effect of correct or incorrect task steps in specific documentation pages.

Evaluate referrer traffic and user behavior

For the deprecated functionality, maybe your proxy metric for success is a lot of referrer traffic to the main migration guide for the change, indicating that it is shared as a primary resource.

Website analytics:

Track referrer data to see if there is organic and email referral traffic to the main migration page.
Track user session activity to identify if users are accessing the migration page from content about the deprecated functionality.

However, there are risks with relying on this sort of data as a success metric.

Quantitative data is limited

Quantitative data isn’t universally or consistently collected for all users across all browsers. For example, referrer data is only tracked if someone’s browser settings, and the website they left, allow that to happen.

As a result, you can’t assume that each user_id that you’re tracking in quantitative data like website analytics or search terms is a specific individual, or just a different browser on the same device One person might be using different devices or browser profiles to access information on your site as part of the same information-gathering session, but might look like separate individuals in your quantitative data.

Associating unique user IDs with specific users is often a fruitless endeavor (unless your documentation site requires authentication, in which case you trade findability for precise user attribution).

Quantitative data is useful, but limited. Treat quantitative data as a supplemental source, rather than a primary one, due to these limitations.

An alternative metric that might be useful if you have partnered with the folks sending customer communications is evaluating patterns in website traffic to the page and correlating those patterns with email send dates, open rates, and click-through rates (if that is data you have access to).

Evaluate user interaction with use cases

For the new feature, maybe you expect to get a lot of clicks on the example use cases and users copying the code samples included, indicating engagement with the content and likely relevance of the code samples.

Website analytics:

Click activity on code samples
Page views on example use case pages
Referrer traffic to example use case pages

Using website analytics as the sole data source to measure success is risky. You can’t derive user intent from user activity directly. Click activity on code samples means that the code has been copied, but not necessarily that it was useful or even ran without errors.

An alternative, albeit harder to measure, metric is organic shares of the content on social media, community forum, support chats, or internal Slack messages. If someone asks for help with the new functionality, do users (not on the documentation team) share your content? Using organic sharing of your content as a success metric again relies on successful awareness-raising of your content.

If you think you did a good job raising awareness of the content but organic shares and user engagement with the content are both sluggish, correlate the documentation usage with the product usage to contextualize it. Is usage of the new product or functionality similarly sluggish, or is product usage high while documentation visits are low, even for a complex feature that you might expect to require assistance from the documentation?

If none of the possible success metrics indicate success, you might need to go back to the planning phase and consider if the use cases and examples that you chose to represent were accurate with the product positioning and customer challenges.

Redo some data collection by reading blog posts announcing the new functionality and customer questions posted on the support chats, community forum, posed to AI chatbots, and shared on social media, then evaluate if you want to make updates to the documentation content to be more relevant and useful.

Evaluate customer journey improvements

For example, if your project was to reorganize the documentation to support specific customer journeys, such as configuring a data connection, you might look for signs that those specific customers are succeeding on those journeys more quickly than before the documentation change:

Website analytics:

Track user session click paths to and through pages related to configuring a data connection to identify if they are shorter and more focused (fewer clicks on unrelated pages in the same session).
Track page views to see if they go up for pages about configuring a data connection.
Track referrals to see if there are more from organic search traffic.
Track search terms to see if there are more clicked results leading users to this page and fewer unsuccessful searches for related terms.

Product telemetry:

Measure the time it takes before a new customer configures a data connection after creating a new account.

User research:

Test users in the target customer group and determine if they can more quickly configure a data connection

Some risks of evaluating these data points to measure success is that your documentation doesn’t exist in a vacuum. Other, related customer enablement or product design efforts can produce similar trends in the product analytics and user behavior data that your content might not have influenced.

That doesn’t mean that your content wasn’t useful, but limits the success that can be attributed to your content if there are other initiatives complementing your work, like dedicated training courses, blog posts, or UI tweaks to improve the process. Those content initiatives are not a bad thing — the goal of documentation is to support the user’s success with their goals (through your product), and ultimately any improvement is a good thing.

For guidance performing qualitative user research on your documentation changes, see Bob Watson’s posts Tips for conducting documentation research on the cheap and Documentation research requires more curiosity than money.

Quantitative data encodes activity not intent

You can’t use quantitative data alone to understand why someone did something, only to track what they did. You know that someone searched for “list widgets” but you have no context about why they looked for that term. You know that your page about dashboard layouts got 10,000 views last week when it usually only gets 4,000, but you can’t know from the site analytics definitively why that is the case.

Because user activity data can only tell you what, supplement it with qualitative data like user interviews, well-designed surveys, and text-rich interaction sources like AI chatbot conversations or community forum data. However, what qualitative data gains in clarity of user intent, it obscures that through difficulty of analysis.

AI tools can assist with qualitative analysis, but there are tradeoffs. Data analyst Randy Au captures them in his posts:

Use data to inform a large documentation project

When you use data to inform a large documentation project, you can more effectively plan the amount, complexity, and type of work associated. As you write and review the content, you can inform tactical choices, inform revisions, and add context to AI-powered tools. When you attempt to evaluate the success of your project, the data you gather and analyze can validate the usefulness of your approach.

Prepare to write data-informed documentation

Tue, 27 Oct 2026 10:27:00 +0000

How you can do data-informed documentation depends on your organization. The data sources available to you, tooling, expertise, support, and time all contribute to the available capacity of your organization to do data analysis, and thus to perform data-informed documentation.

Using data to inform every stage of every project of your documentation practice isn’t the right approach for every writer, or for every documentation team. For some writers, projects, or workflows, it might not make sense to add data.

If you don’t have the analytics capacity, investing in a full data-informed documentation practice might not be worth it right now. I say this not to scare you off, but to set you up for success.

Consider this post the prerequisites for doing data-informed documentation.

Evaluate analytics capacity

Before you start practicing data-informed documentation, assess the analytics capacity of your organization.

The 2026 State of the Docs survey from Gitbook revealed that of the 1131 writers polled, 24% of them do not track any metrics at all. Company size also has an effect:

The measurement gap scales with company size. Medium companies (51–300 employees) are the worst at measurement — 32% track nothing, and those who track average just 1.7 metrics. Enterprise companies (301+) are the best with only 18% of teams tracking nothing.

If you’re one of those writers, that’s okay. You might be at a giant company but be one of those 18% with minimal-to-no data collected and no capacity for correlation across data sources. You might be at a tiny company with a robust data analytics workflow but very few documentation processes that let you take advantage of what you collect.

Depending on what kind of products you document, and how you provide your documentation to users, your analytics capacity can also be different. A SaaS software startup publishing docs on a website has access to different data than a large hardware company that publishes docs as PDF-formatted files or printed booklets included with the package.

To evaluate your organization’s analytics capacity, consider your resources:

Do you have data?

If you want to practice data-informed documentation, you need data. What raw materials are you starting with?

The following data sources provide details about customer and user behavior. For example, some data is submitted directly by customers :

Support conversations. For example, transcripts of support chats in tools like Intercom or case descriptions and comments in tools like Zendesk or ServiceNow.
Search data. For example, search terms used on Google that lead to your documentation site available from Google Search Console or Bing Webmaster Tools, or search terms, result ranks, and clicked result data that you might have available in logs from your documentation site search.
Documentation feedback. For example, votes or ratings, comments, or discussions about specific pages, collected by your content management system or a homegrown solution.
Community forum questions and answers. For example, questions, comments, and feature requests (and the answers) posted on a community forum such as Discourse, or a chat tool like Discord or Slack.
MCP server interactions. For example, keywords used by AI agents to query your documentation on behalf of a user, collected by logging MCP server interactions on the server side.
AI chat conversations. For example, questions asked of an AI chatbot that has access to the documentation (through semantic search or retrieval-augmented generation (RAG)), and the generated responses.

Other data is quantitative and collected when users interact with your product or documentation site :

Product telemetry data. For example, for a software product, click activity and session behavior for users in your product, collected by tools like Mixpanel, Heap, Pendo, Amplitude, or a homegrown solution.
Website analytics. For example, page views, referrer links, session and user IDs, and click activity, such as those collected by tools like Google Analytics or PostHog. If you distribute PDF-formatted files as documentation, determine if you collect download or access metrics for the files.

You might also have access to more ad hoc, qualitative data sources, often acquired through direct research or surveys :

User research reports. For example, the results of research conducted about what users do when they get stuck in the product, the ease of navigating the documentation site, the clarity of the printed booklet, or other documentation-relevant research, collected by a qualified user researcher.
Customer satisfaction surveys. For example, net promoter score (NPS) surveys that include questions about or are specifically targeted to the documentation content, collected by a third-party survey company.
Product reviews. For example, standardized product reviews that might mention documentation, such as those collected by G2 reviews.

Other sources provide details about your documentation, including how your documentation team is working :

Content metadata. For example: last updated date, creation date, title, category, topic length, published version history, and more, collected by your content management system or git.
Documentation content. For example, the content of each topic, including the markup for each piece of content, collected by your content management system or git.
Ticket tracking data. For example, titles, descriptions, and metadata like closed date, created date, issue type, labels, affected customers, and more, collected by a ticket tracking tool like Jira, Linear, or Zendesk.

The existence of the data is only part of the picture — you also need to evaluate if and how you can access it.

Do you have the tools?

To most efficiently and effectively build a data-informed documentation practice, the data needs to be available in tools that make it easy to access, analyze, and correlate data sources. Consider the following:

What tools store the different data sources?
Do you have a data analytics tool?
Can you use that tool to easily process the data?
Is the data in the tool accessible to AI agents, such as through an MCP server?

For example, many documentation-relevant data sources have their own data analysis views, like pre-built reports in Google Analytics or Mixpanel, already-aggregated page feedback and search term data available in a content management system, keyword search term data in Google Search Console, or tables and charts of analytics from your website hosting server.

Without effective data analysis tools, you can easily end up in a nightmare of exported, ad hoc Google Sheet-driven analysis. That can be sufficient for point-in-time analysis, answering a specific question at a specific time, but if you want to increase the analytics capacity of your data-informed practice, you need more effective tools:

If you have a data analytics team, identify if they use a cloud data platform like Snowflake, Databricks, BigQuery, or Redshift to collect and analyze data.
Determine if you have access to a business intelligence tool that makes performing data analysis simpler for non-specialists, such as Sigma, Looker, Tableau, PowerBI, or others.

Do you have the expertise?

The existence of data and tooling isn’t enough to practice data-informed documentation effectively. You also need the expertise available to analyze the data and effectively apply it to your work.

Consider the following:

Do you know how to perform data analysis?
What types of analysis have you performed before?
Do you have access to a data engineer (or team) that can help collect and model data?
Do you have access to a data analyst (or team) that can help design and perform analysis?
Do you have access to mentors, training courses, books, or other resources to help you learn data analysis skills?

In addition to considering your level of expertise (and that of your organization) in preparation for data-informed documentation, consider your time.

Do you have the time?

If you don’t have the time to practice data-informed documentation, access to data, tools, and sufficient expertise doesn’t matter.

Consider the following:

Do you have time to do anything besides write?
What kind of time do you have available for data tasks?
Do you have time to try data-informed documentation on one or more projects?
Do you have time to teach your colleagues about what you’ve learned?

Do you have support?

Just like with time, if you don’t have organizational support to practice data-informed documentation, the other factors are irrelevant.

Consider the following:

How likely is your manager, director, or higher-level leadership to invest in data access for a technical writer? What about tooling and training?
Is your leadership likely to support a time investment focused on delivering data-informed documentation, or more likely to wish that you’d spend your time elsewhere?
What metrics does your organization track, if any?
How data-literate is your management chain?
Are you frequently asked for a single metric that can be used to measure the success of documentation?

After considering your access to data and tooling, the existing expertise of yourself and your organization, the available time and support, you can identify the overall analytics capacity of your organization.

Identify your analytics capacity

Based on your evaluation of your current resources, identify the overall analytics capacity of your organization. I’ve defined the different levels of analytics capacity as follows:

None

Basic

Growing

Defined

Mature

Mythic

No analytics capacity

Your organization collects no data at all, or what data exists is not reviewed or used in any way.

Data might be collected by your marketing team, and not available or shared with the documentation team. It might even exist in a tool that you can access, but can’t be exported and is pre-aggregated and can’t be easily interpreted or correlated.

As far as expertise, you don’t know how to effectively perform data analysis, and you don’t have the support to learn. If your organization employs any data analysts, they’re all too busy to work on documentation-relevant data tasks.

Overall, you don’t have time to do anything except research and write documentation. Getting even a few hours to try using data to inform a small project isn’t something you can prioritize. Maybe you’re an overburdened lone writer just trying to keep up with product releases and falling behind every minute.

You don’t have the bandwidth to review or make use of data, if you are collecting any. You simply don’t have the resources.

At this level, other process improvements might be higher impact or higher priority than adding data or practicing data-informed documentation. More information isn’t the problem. Instead, you might focus on updating the release process to include clear documentation requirements and time allotments, or enabling internal and external stakeholders to contribute to the documentation so that you are not working alone.

To start building basic analytics capacity, see my post Where to start with analytics for documentation or Bob Watson’s post How you can make sense of your site analytics.

Basic analytics capacity

Your organization collects basic site analytics data, such as page views and time on page, but doesn’t know how (or does not care) to use them to affect the documentation process.

Maybe your managers look at the data, but they’re only used as observability metrics to make sure that the site is up, or tracked as part of the company web properties overall. You haven’t built any custom views or explorations in Google Analytics, or poked around in Google Search Console.

Other data that you can access is whatever is available in the dashboard of your content management system — top 10 search terms of the last 30 days, thumbs up and thumbs down votes or ratings on specific documentation pages and accompanying comments.

Any expertise that you have in data analysis is self-driven training. There is no data team, no budget, and no time for official training. You’re comfortable looking at dashboards and reviewing trends, but that’s about it.

You take about an hour or two a quarter to make sure the data looks right and there aren’t any surprises, if that, but that’s about it. For the most part, you have some data, some tools, and minimal expertise, but you’re not really sure what to do with it.

If your organization is at this level, follow the guidance in my post Where to start with analytics for documentation or Bob Watson’s post How you can make sense of your site analytics before you try practicing data-informed documentation with quantitative data sources.

Growing analytics capacity

Your organization collects quantitative site analytics data and qualitative documentation feedback. You might even correlate the site analytics data with feedback to identify high traffic pages receiving negative feedback.

At this level, you have access to your data, you’re aware of it, and you look at it.

However, your tooling might be limited to ad hoc data exports that you manipulate in Google Sheets with some basic formulas.

As far as expertise, maybe you have done some data analysis before, or someone else that you work with, but nothing complex. Building a data engineering pipeline or a semantic model with documentation-relevant data sources is beyond your capacity.

You have some time to work with analytics data too. Perhaps some dedicated time each week, or each month, to review specific documentation metrics and take action, like a triage rotation where you review page quality feedback for actionable improvements.

If you have growing analytics capacity, review the different data-informed projects and pick one that makes sense to try. Maybe you have access to detailed search term details, or have been wanting to dig in to the mysterious depths of MCP server usage logs, so you use data to inform a small-sized project to improve the findability of a recently updated page about a core feature.

Defined analytics capacity

Your organization collects feedback metrics, possibly performs correlation with site analytics data, and also tracks business metrics relevant to documentation, like support chats closed with references to documentation or AI chatbot-driven support chat resolution.

In terms of data sources, you take advantage of the data that you get from site analytics tools and your content management system, and you seek out additional data sources across the company and through direct user research sessions.

Your data analysis tooling likely includes a modern data stack, like a cloud data warehouse to store and analyze data. You might even have access to a dedicated business intelligence tool for data analysis and modeling without needing to write SQL.

At this level, your organization likely employs a data engineer and/or analyst, and either you or a colleague have enough data analysis expertise to build charts and evaluate baselines for various documentation metrics.

You have dedicated time each week or month to review correlations between product releases and metrics for the supporting documentation pages, in addition to reviewing and processing documentation feedback data. You review search term trends in Google Search Console and your documentation site.

If your organization is at this level, you might be asked to define metric-based key performance indicators (KPIs) for your documentation. Your leadership is likely data literate, and you probably are too!

If you have defined analytics capacity, plan to apply data-informed documentation to your next medium and large projects that make sense. It might be easiest to start with a large project (counterintuitively) due to the intensive planning often involved with a large project like a content restructure or product deprecation.

Mature analytics capacity

At this level, you have access to multiple types of documentation-relevant data. Beyond what you get from website analytics and your content management system, you have access to product telemetry data, customer reviews, support chat transcripts, AI-powered conversations with an MCP server and a chatbot.

You have a robust data engineering pipeline, and probably a team managing it for you, along with effective tooling and modeling to make sense of the different data sources. On your own or with the support of a data analysis team, you can perform complex analyses like support case deflection and model user lifecycle activity across the product and documentation.

Each week, you have dedicated time to review unresolved AI chatbot conversations for documentation update opportunities, or have built out dedicated automation to do that reporting and categorization for you.

At this level, your data practice is fully developed. You’ve been instrumenting, monitoring, and analyzing different aspects of a well-defined customer journey for a long time.

With a mature analytics capacity level, you might even be done innovating on the product and instead innovating on the process to deliver product updates as efficiently as possible.

If your organization is at this level, you might be doing data-informed documentation in some cases already without calling it that. In reviewing the data-informed documentation framework, you might find opportunities to formalize or extend some existing data practices in your documentation processes, or otherwise identify gaps in time commitments or reporting that can help improve customer success with your content.

Mythic analytics capacity

At this mythical level, your organization is able to write the perfect documentation for your users and provide exactly what they need. Your site displays only the relevant information to them based on the product configuration that they pay for.

You have access to every data source you can imagine, and probably some that don’t even exist yet. Your tooling is agent-driven automation that runs itself.

You have infinite resources to design and run analyses about anything you can imagine. You actually have someone on the team whose entire job it is to apply data to documentation-relevant challenges and do documentation analytics.

At this level, the only documentation feedback you receive from your customers is requests for more examples.

Grow your analytics capacity

After you identify the analytics capacity of your organization, start practicing data-informed documentation from where you are.

Whatever your current capacity, consider whether increasing your capacity or practicing data-informed documentation helps address your ultimate goal: Help customers successfully use the product.

If you have other priorities that can help you reach that goal more quickly, or with higher impact, then do those first.

This framework can offer you something no matter what analytics capacity your organization has: A guide as you mature your documentation processes, or incentive to collect different data sources.

You don't need to measure everything

Despite this being a post about preparing to practice data-informed documentation, I want to be extremely clear that the path to increased analytics capacity is not infinite data collection. It’s sometimes not worth the trouble to measure certain things.

In a post from quantitative user researcher Randy Au, Sometimes, stuff’s not worth measuring, he has some points very relevant to those of us doing more amateur analysis with limited data:

Seasoned researchers know that they’re making a complex trade between the richness of data being collected, the overall cost to do the data collection, the time needed to complete the work, the extent and confidence that results could be stated, the availability of willing study subjects, the technical feasibility of the data collection, the reliability and repeatability of the data collection. That’s not even a complete list, and on top of it all there’s potentially ethical, social, legal, and political concerns related to collecting data and doing the research.

If you have no analytics capacity, or very basic capacity, focus on starting somewhere relevant. Documentation feedback is an excellent example here. If you don’t have the time, or a plan or process to triage and act on documentation feedback, is it worth it to collect it at all?

The data isn’t everything. You can still write good documentation without data. You can still write bad documentation with tons of data.

We all have limited resources — focus your time and effort where it counts.

It’s also worth noting that as your organization grows its analytics capacity, such as by collecting more data sources, your starting level of expertise might not keep pace. Keep in mind your own professional development and seek out continued education, mentorship, or advocate for hiring a dedicated data analyst to help you continue delivering a high-quality data-informed documentation practice.

Start practicing data-informed documentation

If you’re ready to start practicing data-informed documentation, pick a project:

Large project

For example, refocus a documentation set to split the content by audience and create an administrator guide, deprecate a major feature, or update dozens of pages for a UI redesign.

Medium project

For example, write content about a new interactive workflow to review and assign tickets to specific users, or a new type of widget that you can add to a dashboard.

Small project

For example, add a note that data displayed on a dashboard can have latency of up to 3 days, or update the privileges required to turn on a setting.

Practicing data-informed documentation

Tue, 27 Oct 2026 10:25:00 +0000

It’s alluring to use data to drive every sort of decision and action. When you write content for the web, you can gather all kinds of data about your website traffic. Why not put those metrics to work for you?

The content marketing industry is experienced at using data to guide content development, but documentation isn’t marketing. While documentation can drive qualified leads and be helpful to prospective and existing customers, the ultimate goal is to support users in solving their problems, guiding them through using the product, and validating expectations about how the product should work.

As a result, measuring the success of documentation looks less like calculating the number of qualified leads generated and form fills received based on a specific campaign, and looks more like attempting to quantify usefulness, helpfulness, and quality.

Those metrics can be too muddy to measure, but that doesn’t mean that data can’t be involved in the documentation process. Instead, data can play a critical role in planning, writing, and evaluating your technical documentation. I like to call it “data-informed documentation”.

What is data-informed documentation?

Data-informed documentation is the practice of using data to supplement and guide key steps in the documentation process, namely:

Planning and prioritizing what content to write
Writing, reviewing, and revising content
Evaluating the usefulness and quality of content

Data-informed, not data-driven

I’m intentionally framing this practice as data-informed rather than data-driven. Instead of the data driving our actions, it can inform them. Data is context, not expertise. As technical writers, we have valuable expertise in the product, documentation set, and the audience(s) for whom we are writing.

Use data as an enhancement, not a replacement. If you use AI tools as part of your writing process, specific data sources can quite literally inform the context of your work.

No matter how you craft your content, use your expertise to define the path and the data to help light the way.

Why do data-informed documentation?

There are always competing priorities for a technical writer.

Product development steamrolls ahead, delivering new functionality that needs to be documented.
Customers are contacting support about functionality that launched 2 years ago and hasn’t been updated since, but still gets a lot of use.
Sales is selling effectively, but customer retention isn’t as high as leadership would like.
Engineers keep shipping updates to the API spec without telling you.

The tasks pile up: new feature documentation, important updates to existing content, tutorials to onboard new users, automated review workflows to improve the quality of engineering-driven content.

It’s easy to be overwhelmed by competing priorities or afflicted by the curse of knowledge. When you’re confronting the uncertainty that pervades the documentation practice, data can help reduce that uncertainty to something more manageable.

How to do data-informed documentation

Given how fast-paced a technical documentation practice can be, what does data-informed documentation look like in practice?

Start by assessing the resources available to you and evaluate your data-informed readiness: Prepare to deliver data-informed documentation.

Then, pick a project to work through:

Large project

For example, refocus a documentation set to split the content by audience and create an administrator guide, deprecate a major feature, or update dozens of pages for a UI redesign.

Medium project

For example, write content about a new interactive workflow to review and assign tickets to specific users, or a new type of widget that you can add to a dashboard.

Small project

For example, add a note that data displayed on a dashboard can have latency of up to 3 days, or update the privileges required to turn on a setting.

Make data-informed documentation a practice

As you establish your analytics capacity and start exploring data-informed documentation, consider how to make data-informed documentation a repeatable practice. Build the habits and implement the processes that make practicing data-informed documentation easy:

Set up metrics and reporting in an accessible tool.
Use data to inform your work when it’s relevant, useful, and available.
Automate the reports to appear in Slack or your email.
Make your analytics queryable by an AI agent.

The structure of the data, the tooling available to you, and how you can add it to your workflows is what makes a data-informed practice sustainable instead of aspirational.

As Sarah Deaton puts it in her post, Docs metrics and the stories we tell ourselves:

the real work isn’t finding the one metric that says it all; it’s staying curious, asking better questions, and building a system that gets a little less wrong each day.

Data-informed documentation offers a framework for building that system.