Understanding Documentation as Product

Part 1: The What

Documentation. What is it?

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

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:

  1. Can the user figure out how to use it (usability risk)?
  2. Can we build it (feasibility risk)?
  3. Does this solution work for our business (business viability risk)?

Understanding docs as product

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

Photo by Maarten van den Heuvel on Unsplash

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:

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.

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:

  • 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

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

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

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.

  • 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:

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.

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.

  • “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)
  1. You have a set of success metrics that are meaningful to you, and the stakeholders you represent
  2. 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:

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:

Source: https://twitter.com/DesignUXUI/status/576432203560685568
  • 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:

  • 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

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 “???????”).

--

--

Technical Writer. Former NHS OT and software developer in health tech. I like bikes and plants. www.ioreka.dev

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Lucy Mitchell

Lucy Mitchell

235 Followers

Technical Writer. Former NHS OT and software developer in health tech. I like bikes and plants. www.ioreka.dev