"Docs are beautiful when conceptual docs let the reader see the architecture, or when a tutorial lets them see their own hands on the keyboard. Diagrams and screenshots help, but they often compensate for prose that failed to produce an image on its own. Docs are visible when the reader can close their eyes and still see what the page described."

https://passo.uno/what-makes-docs-beautiful/

#Documentation #DocsAsProduct #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment

For the forseeable future, AI tools will continue to generate such incomplete and sometime hallucinated outputs that there will be a continuing need for a "human-in-the-loop" to not only use several LLMs to review each other's output but to fact-check the final output. Using one LLM alone results in mediocre quality. Using two LLMs results in (sometimes very) good quality. Use three LLMs with human verification for great/outstanding results.

"1,131 people across the documentation industry responded to the 2026 State of Docs survey — more than 2.5x the number of respondents last year. But the size of the sample matters less than what it represents: a genuine cross-section of the people who create, manage, evaluate, and depend on documentation.

Documentation’s role in purchase decisions is stable and strong, and the case that docs drive business value is well established. The shift this year is in what documentation is being asked to do, and who — and what — is consuming it.

AI has crossed the mainstream threshold for documentation, both in how docs get written and how they get consumed. Users are arriving through AI-powered search tools, coding assistants, and MCP servers. Documentation is becoming the data layer that feeds AI products, onboarding wizards, and developer tools. The teams investing in this shift are treating documentation as context infrastructure, not just a collection of pages.

But adoption has outrun governance, and the gap matters. Most teams are using AI without guidelines in place, and documentation carries a higher accuracy bar than most content. After all, one wrong instruction can break a user’s implementation and erode trust in the product.
(...)
Writers are spending less time drafting and more time fact-checking, validating, and building the context systems that make AI output worth refining."

https://www.stateofdocs.com/2026/introduction-and-demographics

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #DocsAsProduct #AI #GenerativeAI

This is so obvious, yet at the same time it seems to me that people rarely really understand what is at stake.

"Most of the breakdowns in a product don’t come from bad intentions or bad work. They come from the way teams divide responsibilities. Engineering focuses on the system behavior. Design focuses on screens and interaction. Product focuses on requirements and scope. Each group works inside its own boundary, and no one is responsible for checking whether all those boundaries line up.

That’s how you end up with a feature that technically “works,” but only if the user magically knows the right order of steps, or already understands a concept that was never explained, or follows a path that only makes sense inside one team’s mental model.

The writer is the first person who has to confront that reality. Not because we’re smarter—because documentation forces us to walk the entire experience in the same order the user will. No shortcuts. No inherited assumptions. No internal knowledge. Just: If I follow this from beginning to end, does it hold together?

That’s when the real gaps surface:

- Prerequisite steps that were never shown in the UI, but the system silently requires.
- Terminology drift where three teams named the same thing differently and nobody noticed.
- Logic branches that exist in engineering’s head, but not in the design or the workflow.
- Error states with no recovery, dropping users into dead ends no one tested.
- Hidden dependencies, like expecting users to configure something before they even have access to it.
- Contradictory steps created by teams working from different assumptions about how something is “supposed” to work.

None of these are “documentation problems.” They’re structural problems that documentation exposes because documentation is the first time anyone tries to describe the system as one connected experience."

https://brandihopkins.com/involve-writers-early/

#TechnicalWriting #SoftwareDevelopment #SoftwareDocumentation #DocsAsProduct #UX

"[T]o build effective docs you not only need tools and content types, but also a model of needs that documentation must satisfy as a product, or of actions users need to accomplish through docs. This model should be fairly independent from the type of software product you’re documenting, in the same way conceptual models of product design and satisfaction abstract away the specifics. Aiming for a general model is necessary because it helps professionals learn and communicate together.
What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.
The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.
As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve)."

https://passo.uno/seven-action-model/

#TechnicalWriting #Documentation #TechnicalCommunication #UX #DocumentationFrameworks #UXResearch #DocsAsProduct

#TechnicalWriting #APIDocumentation #DocsAsProduct #SoftwareDocumentation #APIManagement: "By getting in touch with consumers who invested their time in trying to use the API you're showing you care about them. If you succeed in helping them use the API their perception of quality will increase. And, in the end, you can translate each specific support request into a new use case tutorial. Hopefully, in the future, new consumers will find it and will be able to use the API by themselves.

It looks like documentation is the most important factor in influencing the quality of an API. It's the first thing consumers interact with. It's also the storefront of the API and what everyone will see. If the quality of the documentation is not good enough, there's a high chance the API itself doesn't have enough quality. Investing in writing clear and objective documentation aligned with what consumers want is a priority for anyone serious about building API products."

https://apichangelog.substack.com/p/how-documentation-affects-api-quality