Write better docs with a product thinking mindset

I’ve frequently seen product thinking discussed in product management and user experience design contexts, but haven’t seen it applied to technical writing and documentation. And yet, by applying product thinking to documentation, we can write more useful, relevant, high quality documentation.

What is product thinking?

Product management thought leader Shreyas Doshi defines product thinking as follows in a Twitter thread:

“Product Thinking is about understanding motivations, conceiving solutions, simulating their effects, and picking a path based on the effects you want to create.”

Product thinking is motivations + solutions + simulations to = desired outcomes

As a technical writer, I focus on user problems and the customer journey as a central part of my job, so it seems obvious to adopt product thinking for documentation. While I was working at Splunk, the documentation culture fostered a product thinking mindset, enshrined in the Splunk docs book, The Product is Docs.

Despite being immersed in that culture and caring deeply about helping users, I still found it easy to fall into a “just get it done” mindset, or what Doshi calls project thinking:

“Project Thinking is about understanding expectations, formulating plans, marshaling resources, and coordinating actions to meet those expectations.”

Project thinking is Expectations + Planning + Resources to = Delivered Output

Where project thinking focuses on the steps and process for creating a product, product thinking focuses on the motivation for creating a product and the possible outcomes of that motivation.

Why project thinking is pervasive in technical writing

Technical writers are often short on time and resources. Forced to keep track of multiple teams and projects, we often spend what energy we can on the priorities that seem most urgent. Even with sufficient resources and planning, time crunches still happen. With these limitations, it’s easy to focus solely on churning out documentation and just keeping up.

Project thinking is represented by dev creating a list of features and docs ticking a box for writing docs for each feature

Sprinting alongside engineers, we often adopt engineering practices like breaking our work down into small parts, writing tickets and adding them to sprints to track with developers. With the widespread adoption of CI/CD pipelines in product development, these practices seep further into our documentation processes.

It feels like an optimization shortcut to consider documentation projects in terms of “feature coverage”, much like how quality assurance projects are considered in terms of “test coverage”. Documentation can become another box to tick, making sure that every pull request deployed has sufficient test coverage and documentation coverage for the product functionality.

This “coverage” mindset is ruled by project thinking. What if we took a product thinking approach?

Project thinking vs Product thinking

While project thinking leads us to write documentation that ensures coverage a specific product feature, product thinking helps us focus on what needs to be written and why. Embracing product thinking lets us write higher quality documentation that is more relevant to customers.

That probably seems too good to be true, so let’s look at a specific example—a product making changes to the API endpoints available to developers as part of a versioning change.

Project thinking for API endpoint deprecation

Taking a project thinking approach to the documentation might look like the following:

There might be also be a deprecation plan in the project that includes “Add a banner to the old endpoints with a link to the new endpoints indicating that they are deprecated and will be removed in the future”.  

As a project thinker, this approach has the essentials:

Stage Action
Expectations Document the new API
Planning Docs and engineering work together to produce updated documentation
Provide deprecation information to users
Resources Docs and engineering
Delivered Output Documentation available with new API release and shared deprecation plan

Project Thinking creates a plan with expectations of “Document the new API” + Planning of “Docs and Engineering produce new docs” + Resources of docs and engineering to produce the delivered output, documentation for the new API.

This approach focuses primarily on coverage for the new functionality, and offers some form of continuity for users using the old functionality by alerting them to the change.

Product thinking for API endpoint deprecation

Taking a product thinking approach to the documentation might instead look like the following:

From a product thinking perspective, this list of steps covers the essentials:

Stage Action
Motivations Identify the customer motivations by writing learning outcomes
Solutions Make a list of documentation options that address customer motivations.
Simulations Write a migration guide and draft specific code examples to validate with engineering and product management.
Desired Outcomes Customer achieves business continuity and engineering can deprecate old API endpoints and stop maintaining the code.

Product thinking produces motivations of “Identify customer motivations with learning outcomes” + Solutions of “List documentation options to address motivations” + simulations of “Write migration guide and specific code examples” to = desired outcomes of customer achieving business continuity

This approach focuses primarily on customer outcomes, rather than optimizing for producing a specific type of documentation or specific output that can be checked off a plan.

Comparing the results

If project thinking optimizes for coverage and output, product thinking optimizes for outcomes. The documentation written from a product thinking mindset seems like it’s a lot more detailed, but also slow and resource intensive to create. And it is.

But product thinking is only slow in the short term. If you focus on coverage (and output) instead of outcomes (and customer success), you might have complete documentation, but it’s not as useful to customers. Over time, you might not have many of those to worry about.

Tables comparing project thinking and product thinking documentation output, where project thinking lists “new endpoint”, “new endpoint”, “new endpoint”, “link old to new” with checkmarks next to each item, and product thinking table lists “new endpoint”, “new endpoint”, “new endpoint”, “link to migration”, “migration guide”, sample code

I’m not advocating for abandoning project thinking entirely. We can’t neglect resource considerations or the content delivery timing of what we’re writing, especially if we’re working as lone writers. But just as it’s crucial to consider the timing of what we write, we need to consider the usefulness of what we write. Cultivating a product thinking mindset is essential to writing useful documentation.

Applying product thinking to documentation

It’s easy to fall into the habit of being a “reactive” documentarian, responding to requests for information and rotely updating page after page after page with more information. As technical writers, our priority lists are often shifting or shuffling around. So how do you go about applying product thinking to your documentation?

Approach the documentation itself like a product.

Flow chart that starts with “Create process cues”, then an arrow points to the next step, “Get access to people”, then from there the next step “Write learning outcomes”, then from there the next step “Consider content design”, then from there the next and final step “Test everything”.

Create cues in your writing process, get access to people with essential information, write learning outcomes for your documentation, consider the content design of your documentation, and test everything about your proposed changes!

Create process cues

To make sure you don’t spend too much time on “getting the writing done”, add cues to your documentation process that can help you maintain user-centricity in your writing. What kind of cues? It depends on how you do your writing, but here are some that have worked for me:

Follow a template for documentation tickets. On one fast-paced development project, I made sure that every documentation ticket I filed included the following:

If I couldn’t fill out those details, I knew I couldn’t work on the documentation request without producing poor quality content.

Review and plan your work regularly. On another project, I embraced the essentials of project thinking by spending some time on Friday afternoons reviewing what I’d accomplished in the last week and planning out my tasks for the following week. An output-focused approach that I combined with an outcomes-oriented approach by identifying the key product outcomes or customer goals associated with each documentation task I planned to work on.

Get access to people

It’s impossible to write product-focused documentation with customer outcomes in mind if you don’t have the access to the product managers, engineers, and customers to understand and validate those outcomes.

Make sure you can talk to the product managers, engineers, and UX designers working on your product, but especially take steps to build relationships with sales and customer support representatives that interact directly with customers every day.

Diagram showing a circle with “You” in it with double ended arrows pointing to circles representing other teams at your organization: UX, Sales, PM, Engineering, Support, and Customers

With access to product experts and customer experts, you can more readily identify and validate the customer motivations driving the development of specific product functionality. This is especially crucial in an agile development environment, where the functionality that you’re documenting might only be a small building block of a larger solution, but in isolation it seems clunky and broken. For example, an incident management feature that adds the ability to store information about an incident, but neglects a status field to denote the state of the incident.

With a deep understanding of the why and why now behind product development decisions, you can structure and write your content in a way that accommodates customer goals alongside these possible product limitations. For example, you can write an incident management workflow that includes options for adding a status to an incident. In this way, you’re writing documentation that addresses the existing feature, the customer’s desired outcome, and leaves room to showcase future product functionality.

Write learning outcomes

It’s crucial to understand the customer’s desired outcome when using a product. As the technical writer for a product, however, you also want to establish the customer’s outcomes when using your documentation.

When you write a learning outcome, you want to use active words and be specific. These aren’t abstract user stories, but rather concrete outcomes that customers can achieve.

Don’t write this:

Instead, be specific about the desired customer outcomes:

You need to write specific learning outcomes for your documentation so that your documentation can also be specific and useful to customers.

If you can’t write a compelling and specific learning outcome for a feature, several things could be true:

Writing learning outcomes for every piece of documentation you produce (including the small ones) helps shift you to a product thinking mindset and reminds you why your documentation is important.

Consider content design

Another element of the product thinking mindset is considering new ideas. Content creation can feel routine and straightforward, but it involves design just as much as it involves writing.

Considering the content design of your writing can make your writing more accessible, more inclusive, and more useful. If you include more headers or change paragraphs to a table or a list, your content is easier to scan and therefore more helpful to anyone easily bored, in a hurry, and with dyslexia and/or ADD.

You can also break up paragraphs with visuals such as diagrams or screenshots, with helpful alt text, which can reinforce your content and provide extra learning opportunities for more visual learners.

In addition to adjusting the design of your text, you can also change how and where you present your content. Consider the following alternatives to text documentation:

For example, you could write a blog post to walk through incident management functionality in your product using a common IT incident or a security exploit from the news. This alternate form of content provides a tangible relevant example to customers in a dated blog post that you won’t have to keep updated.

Test everything

To continue treating documentation like a product, you need to test out the decisions that you make along the way. Validate the product motivations you’ve identified, the customer learning outcomes you’ve defined, and take advantage of any and all testing options available to you.

Write better docs with a product thinking mindset

With a product thinking mindset, you build a clear understanding of why you are documenting something. In the end, that clear understanding produces documentation that provides a valuable resource to customers and can even prove to be a differentiator from your competitors.

Diagram reiterating earlier process flow with a curly bracket describing that process of create process cues, then get access to people, then write learning outcomes, then consider content design, then test everything, as comprising product thinking, which then = Better Docs.