Building Better Vendure Docs with Developer Insights

Good documentation shortens the path from evaluating Vendure to building with it. When an important detail is missing or difficult to find, the product becomes harder to use. For a growing number of teams, the person building with Vendure is no longer the only reader.

Docs for Developers and Their Agents

Developers still open documentation to learn a concept or check an API. They also run coding agents that search the docs, retrieve pages, and use examples while implementing features. In those workflows, the agent may read far more documentation than the developer who started the task.

This changes what good documentation means. Developers need explanations and examples that build understanding. Agents need complete, current, well-structured material they can retrieve and apply reliably. We want the Vendure docs to work well for both.

In October 2026, we will begin a broader effort to improve the structure, coverage, examples, and navigation of the Vendure documentation around that goal. To decide what to tackle first, we need more useful signals than page views alone.

We have therefore added developer insights to the documentation website and public Vendure Docs MCP server. They show us what developers and agents search for, which pages help them, and where searches or tool calls fail.

What We Can Now Measure

Page views tell us that someone opened a page. The new insights cover the actions around that visit:

Documentation searches and whether they return results
The search result a developer selects
Positive and negative feedback submitted from a documentation page
Issues reported from individual code examples
Calls to search_docs and get_doc_page on the public Vendure Docs MCP server
Successful, no-result, and error outcomes from those calls
Feedback an agent submits after confirming a problem

A search with no results may expose terminology we have missed. Negative feedback on a frequently visited page can point to an unclear explanation or a missing example. Repeated MCP errors give us a specific workflow to investigate.

These signals help us build the documentation backlog around observed problems instead of assumptions.

Feedback on Individual Code Examples

Every code block in the documentation now has a report action next to the copy button. A developer can flag an example that does not work, is incorrect or outdated, or has another problem. They can also add details about what happened and what they expected.

The report includes the current page URL and the code example automatically. This gives us the exact snippet to investigate without asking the developer to copy it into a separate report.

The report action on a code example in the Vendure documentation

Feedback From Coding Agents

Coding agents consume documentation while working through a concrete task. That puts them in a good position to identify the missing example, outdated instruction, or unclear API detail that blocks progress.

The public Vendure Docs MCP server now includes submit_vendure_feedback. An agent can use it to report a confirmed bug, documentation gap, missing feature, or developer-experience problem.

A report can include what went wrong, the relevant documentation URL and Vendure version, context about the task, and a suggested fix. That gives our team a concrete starting point for investigation.

The tool instructions limit submissions to issues the agent has reproduced or confirmed, rather than questions or guesses. They also tell agents never to submit secrets, personal information, customer identifiers, or proprietary source code.

This lets coding agents report a problem at the point where they encounter it, with the context still available.

How We Handle Feedback Data

We built a dedicated system for the detailed documentation events and feedback rather than sending that content to a general-purpose feedback platform.

Depending on the interaction, a record may include a search query, documentation page, request outcome, Vendure version, feedback category, message, task context, or suggested fix. Documentation search and MCP lookup records are retained for up to 90 days. Explicit page and MCP feedback may be retained for up to two years.

We use these records to find documentation gaps, product problems, and recurring sources of developer difficulty. The Vendure privacy policy explains what we collect and how long we keep it.

What Happens in October

Starting in October 2026, we will use patterns in search, page feedback, and MCP usage to plan and prioritize documentation work. Our goal is documentation that helps a developer understand a concept and gives an agent enough precise context to implement it correctly.

The work will cover information architecture, the path from concepts to implementation, examples for real projects, and content that agents can retrieve and interpret without making it less useful to human readers.