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. In this age of AI-driven development, where docs matter more than ever, users 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 consumers than owning their manuals?

The transformation from bystander to author doesn’t happen by chance. It is a journey you must consciously 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, remove obstacles, and invite people to participate.

Growing reporters from bystanders 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. It’s all quite idyllic, and blind.

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 the information architecture.

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 interacting with those channels.

However, communication channels, be they Slack workspaces or feedback widgets in your docs are not enough if you don’t engage regularly (and, ideally, 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 and being there is the first and most important step in the contributors’ journey.

Reporters can become docs mechanics 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 a positive thing 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 of generosity and community standing: We contribute because it’s the right thing to do, because we can, and because it boosts reputation.

Now, part of what makes docs-as-code an interesting paradigm 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.

When you invite contributors to your table, they can become builders of docs themselves

What if you could also have users (internal and external) write entirely new documentation themselves? 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 want builders because they’re the most powerful advocates for your product.

To cultivate a community of builders and architects, you must move from a transactional relationship to a collaborative one. Reviewing their pull requests won’t cut it anymore. You must grant them access to the bigger picture. This means opening a window into your process: share the docs roadmap, invite them to public planning meetings, include them in discussions about new docs features and sections before you roll them out, much like it would happen with code.

Empowering users as authors is the ultimate act of trust. You formally recognize their leadership by granting them maintainer status over parts of the documentation repository. You give them a seat at the table where decisions are made. In doing so, you complete the cycle. The user, who began as a bystander, is no longer contributing a verse. They are now helping to conduct the orchestra. They have ceased being a consumer of the product narrative and have become its steward.

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. You become the conductor of a symphony where the most beautiful passages are written by people who care about your product so deeply that they’re willing to become its chroniclers.

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. When that happens, you’ll find that the most powerful marketing for your product isn’t what you write about it, but what your users choose to write about it.