Contributing a verse: When users become documentation authors

Docs are a product. Contributing to them is among the finest forms of product engagement. Bystanders can become builders and authors: They contribute a verse so that the powerful play can go on. They cease being the product to become the owners of the product narrative. And in this AI age, where docs matter more than ever, users who write can steer the future of products.

When we empower users and developers to write the docs, we’re opening up products to a form of conversation the likes of which never happens in support tickets or user panels, because it’s public and bidirectional, and an exercise in consensual epistemology: makers aren’t the only owners of product truth; rather, product truth exists in the mind of users and makers alike.

Our role as technical writers and editors is to build the rules and conduits for those docs contributions to happen. Instead of jealously guarding the gates of authorship, it’s our duty to provide users with the tools and guidelines that can help them truly democratize comprehension. Is there a more powerful form of enfranchisement for users than owning their manuals?

The transformation from bystander to author doesn’t happen by chance. It is a journey you must design, beginning with the first user. Communities might still surface even when you don’t care about them, but it’s easier, and better, if you pave the way.

Getting reporters requires comms channels and consistent feedback

Consider a new software application. The first iteration of its user manual, written by developers and technical writers, is the expression of a desire: We want you to use our product and use it thus. What the manual will lack at that point is crashing against the complexities of real usage scenarios. Troubleshooting docs are almost non-existent, guides focus on the happy path, and so on.

That is fine for a while, because the product still needs users. If you satisfy the initial needs of the readers, such as appraising the product, bystanders will turn into consumers of your documentation. It’s the most basic form of engagement. There you want to make sure that they know how to use the docs, that docs coverage is adequate, and that they can find their way around.

As users start flowing into the product, they’ll soon find out what could be improved in the docs or what’s missing. In this sense, tech writing shares with journalism the need for high-quality sources of information. You want to make sure users have effective ways of communicating issues and suggest changes. You turn bystanders into reporters by opening channels and being there.

Communication channels, be they Slack workspaces or feedback widgets in your docs are not enough if you don’t engage regularly (and publicly) with users. Create guidelines and templates for good documentation issues, commit to triage and respond to all issues in a timely manner, and follow up. Listening to contributors is the most important step to get them started.

Reporters can repair the docs when given the right tools and guidance

The next step in the journey is to move from being someone who talks about the docs to someone who is able to repair them. For example, there might be a typo, or a badly formatted code snippet. Perhaps a key step is missing, or a section could benefit from an explanation. Consumers of docs move beyond reporting when they feel confident enough to fix those issues themselves.

This is positive for many reasons: Users have first-hand knowledge of the product and its quirks. They care about finding the right solution and about clarity because what’s at stake is their own success. Contributing to the docs aligns with the Bazaar’s ethos: We contribute because it’s the right thing to do, because we can, and because it grants karma.

Part of what makes docs-as-code powerful is that it opens the docs to contribution, but letting users edit the docs through pull requests is not enough. To become writers, users need to feel they can do so safely and with minimal friction. At this point, they can’t be concerned with your style guide, docs build processes, or information architecture considerations. They just want to edit.

You want to encourage users in issues to open pull requests themselves, but to do that you first need to ensure that you’ve documented how. This is why we added a Contributing section to OpenTelemetry docs, for example. This is also why you’ll want to add automatic checks for links, spelling, style, and formatting. How to Use the Docs should be followed by How to Write the Docs.

In the same vein, you can go a bit further and introduce authoring assistance in your contributors’ environment, under the guise of IDE add-ons and AI agent instructions. For example, you can develop a VS Code extension that validates the special syntax of our docs or their frontmatter. At the same time, you can maintain an AGENT.md file for LLMs to follow when co-authoring docs.

“The probability of a user contribution, P(C), can be modeled as a function of system openness (O), feedback loop efficacy (F), and perceived friction (f). A simplified expression would be:

𝑃⁡(𝐶)∝𝑂⋅𝐹𝑓​ Your proposal is, in essence, a strategy to maximize O and F while minimizing f. It is sound.”

—Gemini on my draft while impersonating a drone from the Culture series

When you invite users to seat at your table, they can become builders of docs

What if you could also have users write entirely new docs? Again, they will not be doing it out of sheer generosity: They’ll want to improve their standing in the community, because they feel that the product has such a great impact on their life that their work can make the difference. You, on the other hand, want builders because they’re the most powerful advocates for your docs.

The maintainers of the OpenTelemetry documentation, for example, host meetings that are open to everyone. New contributors can join the calls, voice their concerns, discuss issues, and suggest improvements. This openness allows the most enthusiastic contributors to step forward and feel included. Even the process to become a maintainer is quite transparent.

Communities then need to get together. If your company hosts regular conferences or events, consider creating a gathering or event dedicated just to docs contributors, as suggested by Alejandra Quetzalli’s Docs-as-Ecosystem:

Hosting local and in-person events such as workshops, meetups, or conferences is an excellent way to bring the OSS docs community together. These events allow contributors to connect, share knowledge, and collaborate on projects.

Opening up the docs roadmap is harder to do when software projects are steered by for-profit companies, because it’s part of wider strategic conversation that might occur behind closed doors, but it’s not impossible. If your documentation is already open source, as well as issues and epics, you can decide to host biweekly or monthly open calls with internal and external docs contributors to get their feedback and ideas, which is an interesting communal complement to UX research.

To reach this level of community contribution requires you to gradually relinquish control. Your role shifts from gatekeeper to orchestrator, from sole author to chief editor of a collaborative narrative. This is where documentation transcends mere utility and becomes something closer to folklore: a living, breathing testament to how real people engage with your creation.