Understanding Documentation as Product

Why good documentation matters, and the theory of product in language processes.

Part 1: The What

Documentation. What is it?

Documentation enables people to use a product to its fullest extent, and meet their needs best.

Example: the first time I got in an automatic car, I couldn’t turn it on. I had absolutely no idea. I spent 15 minutes tentatively prodding buttons and looking for recognisable entry points, then searched online, then eventually called my dad. “Ah,” he said, “usually you have to press the brake and press whatever looks like the ON button at the same time.” If I’d had the right documentation, I would have not have been late that day, or been left with an abiding dislike of silver Prius cars.

Most people are familiar with documentation (or “docs”) for software. Some renowned examples are the docs for Mailchimp, Zapier, or Marvel comics. These are usually a combination of technical (dense, specific) and product (high-level, non-technical) information that isn’t immediately inferable from using the software itself, and requires deeper or clearer explanation.

Documentation matters because it’s how users upskill and learn. Unfortunately, a recent report (2021) estimated that 40% of the time (on average) users are viewing out-of-date documentation (and they might not even realise it), and poor documentation can significantly impact support case volume — not to mention user experience and satisfaction. A particularly interesting insight from the report is that people who make product decisions but aren’t directly involved in documentation (for instance, software team leaders or execs) greatly overestimate the experience they are providing and the impact of their documentation, or underestimate the importance of good documentation. Roughly two-thirds (65%) of executives polled believed that looking for technical content is easy, while only 37% of users felt the same way. Docs also influences first-line adoption (not to mention churn), but again there is a perception gap between leaders and actual users:

Software docs are usually written by people in a Technical Writer role, but the global Write The Docs community equitably and inclusively names us folks documentarians too, for those in differently-named jobs. As well as writing technical and product docs, the remit of the role can cover a number of other communicative aspects.

Historically, adding documentation has often been something tacked on at the end of the delivery process for the main “product” (whatever feature of software that’s being built). I believe that understanding documentation as its own product is beneficial for all stakeholders, because:

“Exceptional technical writers are force multipliers within the software industry. Great documentation makes new hires productive in days instead of weeks, prevents thousands of calls to customer support, is the difference between crippling downtime and rock solid stability, and inspires true, fervent love of development platforms. Technical writing matters.” (Andrew Etter)

The product mindset

Marty Cagan, founder of the Silicon Valley Product Group and former head of product at eBay, Netscape, and HP, is widely recognised as the primary thought leader for technology product management. His explanation of product highlights its inherent user-centricity:

It’s all about solving problems, not implementing features. Conventional product roadmaps are all about output. Strong teams know it’s not only about implementing a solution. They must ensure that solution solves the underlying problem. […] The point is to have a very inclusive and holistic definition of product. You are not just concerned with implementing features.

The product mindset is a paradigm shift away from the project mindset. It’s not a replacement — there is certainly a time and a place where project management is a better tool for the job than a product approach — but it is strikingly different. Barry Overeem, established Scrum Master, explains:

Although project can be a great approach, [it is] often used incorrectly. Organizations kickstart lots of projects with temporary teams whose main focus is to deliver on time, under budget, and within scope. All these constraints are set in stone. When the earlier made agreements made are accomplished, the project has declared a success. […] I rather focus on the actual product instead of a temporary project. Products also tend to have a longer lifetime than projects. Compose fixed, steady teams. Focus on the outcome teams deliver instead of the output. Give teams the freedom and responsibility to think of a strategy they believe will result in the best product for our clients. Facilitate teams in setting up a process that supports them in building these products. Stimulate teams to pull work instead of pushing it.

The product mindset is being applied in contemporary business in interesting new ways — Whereby’s COO, Jessica Hayes, establishing People Ops as product, for instance — and the results speak for themselves. The most recent (2021) report from GitLab and the DevOps Institute highlights an understanding of the product mindset (and pivoting from project to product) as a priority: it is a key mindset in DevOps, and essential in how businesses must adapt to deliver value to users in the near future. The report even flags technical writing and documentation itself as a particularly noted skill (p.34); GitLab really lead the way with this, and have an incredibly strong (award-winning, in fact) documentation culture themselves.

Personally, I think product is one of the best metacognitive/functional taxonomies we’ve come up with as a species. Why? Because it’s person-centred. It’s not about building stuff, continually churning it out. At its core, product is about building the thing that matters; the thing that helps users solve their problems. And from value comes worth.

Two things I want to highlight from this mindset:

The first is the concept of a “minimum viable product” (MVP):

The purpose of which is to build a functional prototype and learn things at the lowest possible cost and effort. An MVP is only made possible because of the deep product and user/audience knowledge of the Product Owner/Product Manager. Part of the core responsibility of a PO/PM is to understand these users and to translate their business needs into product goals; what Jyoti Bansal calls “the classic definition: being the voice of the customer”. Without the user/customer/market, there is no product market fit. Just product. And if no one uses your product, it’s pointless.

The second concept is continually measuring value to improve the product and mitigate risk.

Marty’s opinion is that there are 4 main streams of risk in product management:

1. Will the customer buy this, or choose to use it (value risk)?
2. Can the user figure out how to use it (usability risk)?
3. Can we build it (feasibility risk)?
4. Does this solution work for our business (business viability risk)?

Not only is documentation rarely given the opportunity or resources to take these lines of enquiry, which would make docs more robust and successful, but measuring value is largely a DIY activity in Technical Writing. By understanding docs conceptually as a distinct product, this practice can evolve and improve.

Understanding docs as product

Let’s revisit the use case of documentation for a moment.

Writing is a technology. In the words of Ted Chiang, “a literate person is someone whose processes are technologically mediated. We became cognitive cyborgs as soon as we became fluent readers, and the consequences of that were profound.”

Docs aren’t just “used”. They are integral. Docs are “depended on”. Developers (and myriad other team members, depending on the content of the docs and complexity of the product/company) need docs to integrate with a service, tool, or product. For any something-as-a-Service software companies like Twilio, documentation plays a key part in the developer experience and overall quality of service; it is “crucial to keep documentation valid and to serve it with constantly improved developer experience based on user feedback.” Twilio actively sought and collected (and shared!) insight about the behaviour of their docs users, and used it to meet those user needs better. Smashing out beautifully-formatted tables is not the sole deliverable of Technical Writing: it’s using a particular technology and crafting knowledge accurately for your users to excel.

Photo by Maarten van den Heuvel on Unsplash

Andrew Etter, Senior Technical Writer at AWS and author of Modern Technical Writing, points out what all Technical Writers know: first and foremost, we are testers and researchers. Our job is to know what people want (or need) to achieve, and precisely how to achieve it. Communicating that knowledge is the last step of the process and — for many — rarely takes more than 10–20% of our time. That combination of multiple stakeholder management, deep contextual user knowledge, and tying user goals to business metrics and outcomes already aligns closely with product principles.

Technical Writers are the perfect PM/POs for docs as they understand the systems thinking approach. Documentation can be far more complex to architect than it appears. Why? Because there are different strata of users, many variables affecting construction of a well-maintained technical system, and — most importantly:

Writing is hard. Writing well is even harder. Writing well consistently is even harder than that. Having multiple writers writing well consistently with a consistent style is the hardest of all. — Jessie Evans, Splunk

In addition, creating an information architecture that scales (when one appreciates that (thank you Donna Spencer) taxonomies and semantic groupings are in the human brain, and far from objective) is another challenge altogether. But despite the challenges, I believe documentation is a very cool product and I love working on it. The docs product is knowledge, and the power and autonomy that brings to its users. Isn’t that incredible?

A handful of tech companies have the mindset and resources to easily already see docs as product — like Stripe, or Twilio, who specifically state that they consider their API docs “a product in its own right, not just a supplement of “The Product””, or Splunk, whose docs team wrote an entire book I consider essential reading on this topic: “The Product is Docs”. But you don’t need lots of money or people (I mean, it helps) to keep those two aforementioned things in mind: an MVP based on your very knowledgeable user understanding and empathy, and gathering feedback to inform the continual iterations. You can start today.

Part 2: The Why

I’ve split my argument — understanding docs as product — into sections.

1. It benefits the people who build and maintain the docs

I’ve always enjoyed Splunk’s anecdote:

At [x company], all employees can edit the documentation. When we mention that to many tech writers, they look a little pale and shaky. Perhaps they’re imagining a management directive handed down to them: “We’re a collaborative company! Just imagine how up-to-the-minute our product documentation will be! Anyone can add content so surely everyone will contribute!” They entertain fearful thoughts of chaotic information architecture, duplicate content, circular logic, long-winded diatribes in the form of knowledge articles, and a manifest ignorance of the finer points of grammar and clear writing. Further, this anxiety extends into what has been referred to as content ROT (redundant, obsolete, and trivial). If everyone owns content creation, then no one owns it, right? And if no one owns it, no one will validate it, update it, curate it, or kill it when necessary.

Let’s read that last line again.

If everyone owns content creation, then no one owns it, right? And if no one owns it, no one will validate it, update it, curate it, or kill it when necessary.

This is precisely why products have Product Managers or Product Owners, and why you should not only have a Tech Writer (team), but they should be recognised as the owner of their product. Many Technical Writers are already doing this metawork, functioning as de facto POs in their cherished and grammatically correct fiefdoms, and it behoves companies and teams to support them to do more of it. Don’t get me wrong — some Technical Writers have a role where the scope truly is mostly to write; “suum cuique” (to each his/their own). But, as with the term “engineer”, the title can cover a great variety of bases. Flexibility, ingenuity, and insatiable curiosity is, in my opinion, one of the defining characteristics of a Technical Writer who truly loves their work, and I can honestly say every product person I’ve met shares those traits.

Sarah Drasner’s wonderful Career Ladders example for Technical Writers shows — especially at Senior level — a lot of the responsibilities are already product-mindset-focussed, though product isn’t mentioned at all. With such pre-existing dovetailing, understanding docs as product isn’t a paradigm shift. It’s an insightful new lens for the same profession, and it supports our documentarians better, making even more use of their extensive skillset.

2. It benefits the organisation

Documentation can be described as an “integrated content experience” (a Splunkism I love) and involves teamwork and logistics in multiple directions with a lot of stakeholders. It’s a constant exercise in information gathering and precision distilling in a single location, so individuals don’t have to continually ask the same questions. In that way, good docs reduces the burden of many-to-many communications on businesses and employees, which (if we accept Conway’s law as accurate) tends to produce “monolithic, tangled, highly-coupled, interdependent systems that do not support fast flow. So while “more communication is not necessarily a good thing” (ibid), getting it right can make a huge difference to businesses and individuals.

I often find a parallel between marketing and docs (though they tend to address different audiences and I’d argue only the latter aims to actually meet user needs). Peter Thiel, billionaire entrepreneur and co-founder of PayPal, said it most succinctly:

“If you’ve invented something new but you haven’t invented an effective way to sell it, you have a bad business — no matter how good the product.”

To me, this mirrors the way “real heads” feel about documentation (and is in fact the philosophy behind Documentation-Driven Development):

“From the perspective of a user, if a feature is not documented, then it doesn’t exist, and if a feature is documented incorrectly, then it’s broken.”

At its most basic, docs is an interface between engineers and customers with the potential to springboard use. Many (but by no means all) engineers are so fabulously competent at the technology that context switching to a user experience paradigm isn’t frequent, rewarding, or necessary. Both Technical Writers and Product Managers have known this since day 1; another symmetry. Engineers and customers often have different requirements of what “value” is in a technical product, including the docs. Technical Writers are there to make sure everybody wins, including the business. Focussing on making your docs “10x better” (another popular Thiel soundbite) has a knock-on multiplying effect that many other functions will not.

Much like Philip Pullman’s explanation of exposition in David Mamet’s films, Technical Writers don’t just string words together or collate walkthrough steps, they think “where do I put the camera?” and tell the story (explain the information) in the way that best fits a specific user group. As access to the main software product is often intricately bound up in comprehension, dedicating the resources to building the best possible docs to fit your users (rather than just writing stuff down and hoping for the best) therefore drives adoption. In addition, actively seeking and incorporating user feedback and involvement demonstrably improves business outcomes — just ask the NHS why they use “patient activation” in their services. Docs is a relatively low-risk product where business can make the most of this opportunity.

3. Most importantly, it improves the quality of the docs…

Having a Tech Writer who functions as a dedicated, recognised PO/PM for documentation means it is expected that the docs functions, grows, iterates, improves, and thrives like any other product. One thing I’d love to see more of is innovation in documentation — though there’s plenty of cool stuff happening already (thanks, WTD community!). Ryan Paul, for instance, explained last year how Stripe’s technical docs are pushing the envelope in the way that’s right for them; treating documentation as more of an application and enabling interactive user content to improve UX:

• Contextually aware, dynamic content such as geographically-relevant API documentation and dynamically reordered sidebar content based on relevance to the user’s profile and role
• The user’s own API test key is generated inside all code examples, enabling them to copypasta and immediately use the examples
• Checklists on Stripe’s “Getting Started” pages are persisted in local storage (so the user can keep track of which steps they’ve already completed), and boxes are auto-checked where possible — for instance, if the user already has 2FA enabled, Stripe docs will auto-check that box for them

Stripe, which migrated from Ruby/ERB and now builds its docs on React and a self-built tool called Markdoc, aims to blur the boundaries between the docs, the Dashboard, and the API reference — its main products. Embedding functionality by building using the same tools is essential for this, ensuring consistency both in UX and in author/dev experience. Also, and this is a personal favourite, they can TEST THEIR DOCS LOGIC CODE, which means it’s both more robust and easier to maintain.

Mixing code and content is a powerful paradigm, but difficult to scale, and comes with a lot of challenges. However, treating docs as an application means you can decouple code from content (restoring simplicity and re-lowering the barrier to contribution), and because page logic is expressed declaratively, it is a first-class citizen in the AST. The prescriptiveness of the setup means that everything is automatically consistent between all Stripe’s docs — I become glassy-eyed with dreaminess at this point, because maintenance and consistency can be a pain in scaling docs. It’s important to note, however, that “improving the quality of the docs” from a product perspective does not mean “meeting style guides more consistently” or “replacing all 4-spaces with tabs”. It means meeting user needs better — including the TW as a user.

4. … and improving the docs quality benefits our end users

The product mindset requires fundamentally changing how you think about delivering value.

A product mindset is a holistic approach to delivering value for customers — prioritizing continuous evolution, data-driven decisions, and customer delight.

So what does it look like in practice? Teams with a product mindset are strategic, agile, and customer-driven. They typically take a long-term view of what they offer, delivering and iterating frequently to improve the overall experience. They focus on outcomes rather than output, and measure success by the value they create for customers and for the business. (Brian de Haaff)

Understanding docs as product means acknowledging that our prime directive is to build effective docs for our users, and WIIFM (What’s In It For Me) is the secret to user engagement. It also means acknowledging a subset of users who often get overlooked: novices. These users are often trying to construct the mental model necessary to even begin to use the service or platform. If you don’t provide this (for instance, if all your docs are written by experienced developers rather than someone taking a product view), you’re delegating the work to them, and taking no responsibility for their experience being sub-par. How are they supposed to step up their learning from this shaky base? How will you guarantee they can competently and painlessly use your software to achieve their aims? This is the antithesis of delivering value to customers.

Tom Johnson, probably one of the most renowned Technical Writers of the present day, agrees:

“Documentation often fails to tell the who/what/when/why about the product. Anemic overview pages provide little detail about what the product even is before jumping directly into how to configure it and install it.”

This is a “gamechanger” in writing excellent documentation and empowering your users to meet their own needs, so we shouldn’t just focus on technical accuracy, but take a holistic, user-centric approach.

The time is now for improving our docs (technically, the time was yesterday, but everyone is busy); Google themselves admit that “as working from home becomes more common, good documentation has never been more important in enabling software engineers to work independently.”

Lastly, I believe understanding docs as product gives documentarians a platform and framework to capture truly diverse feedback as best practice. Pursuing, collecting, and actioning feedback from “demographic diversity in all of its many facets, diversity of thought, diversity of personal background, diversity of educational experience, diversity of personal and professional interests, diversity of learning styles, and more” (Splunk) is essential to creating documentation that promotes digital equity. I remember the opening copy of a Wellcome Trust job ad I saw once: “Technology is not neutral. Who builds it, what it does, how it’s made and how people using and affected by it are involved and central to making sure the benefits of digital technology in science and health are experienced equitably.”

Quick case studies: product, growth, feedback, and technical content

Look at Elsevier, one of the biggest science publishing companies in the world, pivoting from “a publishing company that assures quality control in scientific output (although this will remain important) [to] a researcher productivity & analytics company that assures better outcomes in every interaction within the scientific world”. They are revising their technical content to make it work better for their users, because that is what their users now need. How did they know? Feedback.

Look at the NHS, who reviewed their entire administrative capabilities (communication and documentation). Read through these key points and consider the tremendous impact this content has, and why it is important to get and act on user feedback:

• High-quality [written content in admin] has the potential to improve patient experience, reduce inequalities, promote better care — and contribute to a better working environment for staff. Despite this, it has seldom been a major focus for policy-makers and leaders.
• Embracing a user perspective, seeking and harnessing patient feedback, and working with patients and staff to co-design processes will be essential to developing truly high-quality admin in the NHS.
• Recent analysis of the English Cancer Patient Experience Survey revealed that the co-ordination and administration of care were the strongest predictors of patient satisfaction with cancer care, across a diverse range of patient groups and treatment pathways.
• Patients and NHS staff are affected by admin processes on a daily basis — and patients often turn to staff for help when they encounter problems with accessing and navigating care.
• For some, the cumulative effect of communications that do not meet patients’ needs contributed them perceiving their overall experience of care as lacking dignity and respect.

Part 3: The How

Carve out new feedback channels

I know you’ve read a lot already, so the tl;dr is something you already know, but might not think about with regards to docs:

Continuous feedback leads to continuous improvement.

If organisations are constrained to produce designs and teams and systems and products that reflect current communication paths, the way to build better products goes hand in hand with having improved communication flow where it’s needed, and better quality data. For instance, when the Obama team overhauled the US healthcare system and wanted to make a shift from volume to value, they started with a wired healthcare system — one that “tracked patients, measured outcomes, and detected and swiftly addressed instances in which people failed to receive the care they needed.”

From a product perspective, without customer feedback, you’re literally just guessing. Andrew Spittle points out the missing link in the world of docs:

When you’re developing a product you don’t ship something and passively wait around for it to become popular. If what you shipped isn’t gaining traction you iterate. You tweak and adjust until your product fits its addressable market.

For some reason we don’t approach documentation with the same mindset. Our predominant expectation is that we can ship docs and expect every person to read them. If the docs have up-to-date screenshots, are detailed, and are searchable then that’s enough. If people don’t read, that’s their fault not yours. That’s a fundamentally broken expectation.

Most importantly, if you react to support requests by wondering why people can’t read the docs then you are missing a golden opportunity. You are directly blaming the person using your product instead of blaming your product for requiring documentation in the first place.

The Splunk docs team, in particular, remind us in their book that when it comes to documentation, feedback is data, and data is powerful. Using data to think algorithmically about your world or professional microcosm, “learning about the fundamental structures of the problems we face and about the properties of their solutions”, helps us see how well our product is performing, and better understand the areas in which we can improve it. Cagan’s advice is to pursue both qualitative learning (to understand why users and customers behave the way they do), and quantitative learning (to understand what they are doing). Getting user feedback and course-correcting your docs is the definition of ongoing value exchange and rich, data-driven, continuous improvement. I like Will Larson’s gamification of product management: “it’s an iterative elimination tournament, with each round consisting of problem discovery, problem selection, and solution validation.”

Measuring what matters

Riona MacNamara, Technical Writing Manager at Google and regular contributor to open source and the Write The Docs conferences, loves asking job applicants how they think (or know) their docs are any good. Not only are the answers revealing, the concept itself can touch on so many different areas, providing fantastically kaleidoscopic insight.

You know how you know your docs are good? You test them. You find out. You use data — of myriad types — and your continually-growing professional insight to know how to do better. All the time.

Being able to demonstrate, in a data-driven way, the impact and value of what Technical Writers do and contribute to users and businesses is so important… and somehow still not commonplace yet, instead relying on other teams’ success metrics as an inherited form of value. A product mindset bakes in the capability to define documentation quality, its requirements, measure our success, and communicate our value, all as standard.

Riona puts forward the concept of measuring structural quality vs functional quality (such as you’d find in software testing) in documentation. Structural quality (grammar, syntax, style guide adherence) is usually binary (or at least discrete), and thus easy to measure, and easy to report. Functional quality is more qualitative, and is based on whether the documentation is, basically, effective or not. It’s also the much weightier consideration when deciding whether docs are “good” or “not good”. I like this idea because it’s another demonstration of inherent user-centricity. Like the joke about car parts (“what do you get if you cross a BMW engine, Lamborghini wheels, Jaguar suspension, etc.? An expensive pile of junk.”), having “perfect” docs is only “perfect” for machine-readable data. It’s a natural language processing dream; it doesn’t necessarily mean it’s good (or “effective”, the highest accolade) documentation. In the video linked at the start of this paragraph, Riona calls structural quality merely “pretty” — “it’s not the ultimate source of our value, and doesn’t define our worth” — and it can cost us dearly when we focus too much on it at the expense of other aspects. Measuring structural quality is precise, and might look good on a chart, but it doesn’t really provide much. It isn’t very informative or persuasive, but it’s easier to collect and collate. Functional quality usually has stronger links to how we explain our value, and that’s why we need to capture feedback on it.

The Splunk docs team are ahead of the game on this, and share their learnings (many thanks!):

When we think about measurement, we think about precision. This habit of mind arises because we establish our thinking about measurement in terms of the physical world: from construction, cooking, or medicine. In those contexts, we measure precisely because there are physical consequences if we cut the board too short, add too much baking soda, or prescribe the wrong dosage. Measurement in the less-tangible world of business is admirably clarified by Douglas Hubbard. His book, How to Measure Anything, argues eloquently that the purpose of measurement is to reduce uncertainty so that you can make a decision based on the results. In other words, measurement isn’t about precise counting, and measurement has to support a business decision.

Once again, this is a product mindset without the word product, and was mentioned at the start of this article: continually measuring value to improve the product and mitigate risk.

Relative correctness and the “success” paradox

One particular thing I like about product is that it overtly states that success feels and looks different to different stakeholders, instead of holding it as an uneasy combination.

Consider what these experienced Technical Writers consider their output to be:

• “Achieving the level of detail the audience needs to be successful.” (Splunk docs team)
• “Ensuring I support my users become badass at developing mobile and web apps.” (Joao Fernandes)
• “Our output is not “docs”. I consider my output to be happy productive engineers, and being better aligned with our teams.” (Riona MacNamara)

To me, this mimics what Todd Jackson says about reward centres in the PM brain (mentioned in Robert C. Martin’s Clean Code): “There’s several big ones I can think of: having impact, delighting users, sense of purpose/mission, having autonomy, getting recognition, financial outcomes, learning/growth, etc. In my experience, more than other disciplines, PMs tend to care most about impact and autonomy.” Once again, to me, it feels like Technical Writing and documentation is already basically a product. There’s more we can leverage from this.

However, other people have competing priorities and ideas of “success”. Engineers, in my experience, want absolutely everything documented, but creating comprehensive docs is not the same (and nowhere near as important) as creating relevant docs.

To some people, like Mark Baker, mean time to productivity (MTTP, a common devops metric) is the one true success metric for documentation. Once again I’ll lean on Splunk’s work here:

Philosophically, he’s right. The true purpose of your documentation is to educate your customer about how to use the product, either while they’re learning about it or using it to do their tasks. The faster your documentation makes your customers productive, the more successful it is.

To others, success is “the docs were written painlessly”. These people usually take a top-down approach to docs (“here’s this API that needs documenting”) not the user-centric, bottom-up approach. As the sole tech writer on a large team (4+ scrum teams, complex product, multiple projects) with limited bandwidth, the least I could do was instigate having a docs ticket per Epic, organised from the POV of the user(s) who needed information, and what exactly these docs needed to achieve (a combination of user-driven development, and aiming to satisfy what Riona would call functional requirements).

Different companies manage this in different ways. While I personally prefer the bald “start from the user/user needs and work backwards from there”, some condense this into a snug (or smug) agile-esque style: User Story-Driven Development, or Readme-Driven Development, or learning objectives, or… you get the picture. Frankly, I don’t care which one you use, as long as:

1. You put the user first
2. You have a set of success metrics that are meaningful to you, and the stakeholders you represent
3. You dedicate resources (scheduling, planning, money, people) for this documentation. Docs is a product and deserves/needs more than a line in a planning wiki page somewhere that you’ll “get it ticked off” or add it on at the end. And on that note…

Good content happens upstream

Caroline Finucane, Lead Content Manager for the NHS’s COVID-19 testing program, captures the plight of “tacked-on” written user-facing content teams everywhere:

“This may seem obvious [as a problem], but when the testing programme started, content designers were only aware of new programme requirements when the solution had already been decided and half signed off. […] It’s awkward asking everyone to rewind so we can design a solution based around user needs, rather than what stakeholders feel we need to convey. It’s frustrating also to the delivery lead who thought we were almost there, and the team who got us to this point, whose work we might not be able to take forward.”

Caroline’s blogpost talks a lot about how content/a senior content lead can positively impact user journeys, solve broad pain points, and be an essential part of strategy. “Let’s recognise the need for a content lead at a senior level. Programmes need more than just a talented wordsmith in charge of approving content” — just as great docs need more than just a spellchecker.

User-facing written content, such as docs, is not the dusting of icing sugar atop the baked and cooled product tart. If you are going to achieve product market (or product market sales) fit, user-centred content conversations need to happen FAR earlier in the feature pipeline. You need to be as clear in the planning stages about which users need to be updated on which aspects of the changes or new feature as you do on the technical implementation. In fact, when continuously adopting a user-centric product mindset, the former may well influence the latter.

Why this matters to me: docs is a complex, wonderful, powerful tool, and deserves product scope

On a personal note, understanding docs as product gives me the vocabulary and infrastructure to (finally!!) proselytise and explain the scope and depth and complexity of this professional area. It is such a unique and charmingly academic human endeavour. By elevating documentation to “product status” rather than simply “product constituent” I have a platform to point out elements like:

• Of course good documentation is important — it is how your users build mental models of your software or platform or product. The aforementioned Ted Chiang, award-winning author of many fascinating short stories including the one behind the Sapir-Whorfian film Arrival and actually a Technical Writer himself, puts it beautifully: “And words were not just the pieces of speaking; they were the pieces of thinking. And when you wrote them down, you could grasp your thoughts like bricks in your hands and push them into different arrangements.” Of course you need good documentation. Do you think people just jump to the right conclusion all the time? Come on, we all know how users are with a new product if left to their own devices:

Source: https://twitter.com/DesignUXUI/status/576432203560685568

• You need a special kind of nerd to be Product Owner for documentation. Product people in general tend to lean towards being the outrageously efficient Swiss army knife-people of the professional world, but being a product person with a passion for linguistic meaning and grammatical pedantry is a true calling. It’s like the syntax illuminati crossed with deep empathetic skills fighting a quiet global crusade over the styling of nested lists. I have never met a Technical Writer who wasn’t happy in their job or thought their work didn’t have the potential for positive user impact. The eternal bunfights about the Oxford comma are part of the culture. That passion (or interest, or drive, at least) has been something I have really appreciated, having come from a software product background myself. I’ve always cringed when businesses use the term “customer-obsessed” because it sounds like Regina George in a powersuit looking for Pepe Silvia, but docs POs (people like me) really do care about what they do.
• The user empathy drives one of the most interesting aspects of documentation: the curation of information. A very human (and ongoing) pursuit, even in tech: “The value of curation is never just about selection. It’s about knowledgeable selection, knowledge you can’t fake. It’s this mastery which makes curation so significant. […] Curation is, in part, about what machines cannot do.” (Michael Bhaskar). There is certainly a place for machine-driven documentation (I’m looking at you, Swagger and auto-generated changelogs) without reducing it to Orwellian “writing machines”, but it is the skilled human curation and dedication that crafts any documentation that works and keeps working. In an echo of Riona’s functional/structural dualism, I hear Philip K. Dick: “empathy, evidently, existed only within the human community, whereas intelligence to some degree could be found throughout every phylum and order including the arachnida.” I’m not implying machines could never create wonderful documentation, but I don’t think we’re there yet. There is still a huge role that a dedicated, skilled Technical Writer and docs PO has to play to build the right thing to meet user needs.

Takeaways

You’ve done brilliantly to get this far. I am grateful! Here’s the bite-sized takeaways, the vol-au-vents aux docs:

• Own it: fight your docs corner. You know it matters, so convince everyone else with your belief
• Specify it: your goals must be more specific than “write good docs”. What does that even mean?! Good for whom?
• Measure it: product and user telemetry is the only way to know what to prioritise. Measure what matters, talk to your users. Counting isn’t measurement; not all that counts can be counted
• Improve it: Treat docs as a product and continuously improve based on the feedback you collate. CI/CD it and use the best parts of agile to drive product market fit between your users and the software
• Yolo it: being overly protective of your work will make you miss out on opportunities for improvement and growth. Also, the ability to be experimental is highly correlated with the technical practices that contribute to continuous delivery
• Work it: work smarter, not harder. Implement changes that positively impact your users, or have a multiplying effect on functional, not just structural, quality
• Backlog it: channel your inner PM and log ALL design, tech, and content debt. These debts are barriers to achieving UX goals, and this matters
• Masochist it: actively look for pain points in your UX. At the very least it gives you a concrete conversation-starter, and remember: “having a conversation that reveals disagreements is a sign of success in addressing issues”
• Defend it: promoting user-centricity is a culture. Go to bat for your users in the meetings they will never attend: their needs matter
• Don’t over-do it: big docs != good docs. Growth comes from adding value, not from adding more

Tl;dr — documentation is not an adjunct to the software. It’s not a side dish or a postprandial limoncello or some kind of literary back-up dancer. Good documentation is a provably vital component to a thriving product, and a product in its own right.

I will now leave you with my professional experience in meme form:

Resources

All books referenced can be found in my commonplace book, and I reckon they can be purchased from a nice local independent bookseller near you. I’ve tried to link them in situ rather than a long list here, so you can click the link in the context of the phrase or idea referenced (I often open tabs then come back to them later, thinking “???????”).

I am especially grateful to Christopher Gales and the entire docs team at Splunk for their output (“The Product is Docs”, now in its second edition), their comms, and their trust. In particular, the core idea that documentation helps your users “build mental models” is a systems-thinking-Splunkism I would adopt as a family member if I could, because it’s particularly terrific use of language, and I am grateful to be able to reference it. Thank you!

If you spot something I’ve mentioned and it’s not referenced or attributed correctly (or at all! Good grief) please do reach out to me — you can find my contact details at www.ioreka.dev. Please assume best intent — it will have been an oversight on my part and I’d welcome your clarifications.

Thank you to Richard R. for not only spotting a broken link to ZoomIn but also emailing me with the updated, correct one! Much appreciated.

To read more about the product mindset, I recommend this short Medium post.

Thank you so much for reading. I really appreciate it.