Purity of purpose and the art of writing modern product documentation

Modern product documentation has evolved beyond the sole purpose of conveying information. It also plays a crucial role in meeting various business demands, such as building brand reputation and customer trust, sales enablement and marketing support – along with user adoption and engagement. At its core, modern product documentation must be intentional, and it must anticipate certain user outcomes.   

Gone are the days when documentation merely provided assistance in setting up features or resolving errors. Today’s product documentation should aim to influence user behavior, serving both short-term and long-term outcomes. Technical writers can accomplish these goals by adopting a proactive approach and crafting purpose-driven documentation. 

This blog post explores the significance of identifying a user-centric purpose when writing product documentation and maintaining it throughout the document to deliver intentional, outcome-focused help articles. Whether you are a seasoned technical writer or a beginner seeking to enhance your skills, this post aims to help you unravel the philosophy and strategy behind writing purposeful documents so you can master the art of writing modern product documentation. 

The contents of this post: 

Creating purposeful documents involves a two-step process. The initial step entails identifying a suitable purpose for the document, while the subsequent step focuses on consistently maintaining and delivering this purpose throughout the entirety of the document. 

Identifying the purpose of a document 

It’s crucial to understand from the outset that the purpose of your documentation should be your user’s real-world outcome.  

For instance, let’s write a help article about setting up a channel manager integration.  

A clear title, "How to set up X integration," establishes user expectations from the beginning. 

The introductory paragraph provides background information, addressing questions about who can perform the task, where it fits within the system, why it is necessary, when it is done, and what the integration is about. This paragraph serves as a concise yet rich summary of the task at hand. 

The main content of the "How to..." help article typically comprises an ordered, step-by-step list of precise instructions.  

It's worth highlighting here that the technical writer's job and the purpose of the article is not dependent on whether the user successfully sets up the integration. The user’s true purpose is to increase revenue with the channel manager bookings derived from setting up the integration. 

To reiterate, the user’s purpose is not reading the help article to “set up an integration” but to “receive channel manager bookings and increase revenue.” 

Identifying the one true purpose of your document means identifying the user’s real-world purpose.  

Once the true purpose is identified, maintaining it throughout the document becomes essential, ensuring what I refer to as "Purity of Purpose". 

Purity of purpose 

Purity of purpose means attaching a singular identified purpose to your documentation and sticking to it all the way through.  

Overloading the document with multiple purposes at best confuses users and at worst deters them from the primary intended purpose. When your document never wavers from its one true purpose – “Increase revenue from channel manager bookings” for example – it adds lot more value to your user than just “setting up an integration”. 

Purity of purpose makes the writer’s job that much simpler and more streamlined: to include all information essential to achieve this real-world purpose. Maintaining purity of purpose brings about various far-reaching benefits, including: 

• Establishing clear expectations for both the writer and the user 
• Enhancing the clarity and effectiveness of the documentation 
• Streamlining content to prevent overwhelming users with irrelevant details 
• Facilitating better content management through distinct categorization of content 

Purity of purpose in publication channels 

Purity of purpose also extends to the content publication channels beyond the traditional help database. This includes release notes pages, email communications, in-app help resources, and help chatbots, among others.  

By extrapolating the concept of purity of purpose from product documentation to these publication channels, organizations can identify the one true purpose for each content channel.  

For instance, release notes may aim for "effortless user adoption of new features" rather than simply "broadcasting new features." Similarly, a help page should strive to promote "users choosing self-service to resolve issues" rather than mere passive reading of help articles.  

Maintaining consistency across product documentation and all content publication channels with this "purity of purpose" approach yields significant real-world outcomes for organizations, including the development of a self-sufficient community of "super users". 

Super users and their significance 

Super users are those product users who possess a deep understanding of how to leverage product features to their advantage. They play a pivotal role in driving feature adoption and contributing to the success of both the product and the organization.  

Super users actively engage with the product and add value to the user community. They are the “influencers” of your user network. You can find them on your organization’s power user curve.  

Super users willingly share their knowledge within the product community and prefer self-service for problem resolution. An increase in the number of super users who are motivated to self-serve means lower customer support costs for organizations, as illustrated in the figure below.  

Mews’ commitment to user-oriented content 

In my role as the Content Manager at Mews, I have the privilege of guiding a dedicated team of technical writers who pursue a purpose-driven approach, aiming to motivate self-service capabilities among our users. Our primary focus is creating user-centric and outcome-based documents. Here’s an illustration of our approach: 

You can see that although the title is “Adding minibar items...” the sections in the article cover all the information that would enable the user to activate the feature and finally view the added items in the customer’s bill using the Mews app. That’s the real-world outcome that the user wants to achieve. The article also informs the user about the exceptions to this action, right at the beginning.   

Summary 

The essence of modern product documentation lies in its purity of purpose. Writing purely purposeful product documentation offers numerous benefits for users, writers, and organizations alike. By creating purpose-driven documentation, technical writers can cultivate a community of super users who can fulfill their real-world purposes.  

Technical Writers in the current business environment need to write product documentation with the aim of creating product super users by identifying and satisfying their real-world purpose. Write with the purity of that purpose!