The right documentation, in the right place

EventCatalog 3.15.0 is out, and it introduces resource-level documentation.

The catalog lives in one place. The runbooks live in Confluence. The ADRs are somewhere in Notion. The troubleshooting guides are in a Slack thread from six months ago. The catalog tells you what exists. Everything that explains why and how is somewhere else entirely.

EventCatalog has had custom documentation support for a while now. The ability to bring your own docs and create a global documentation section inside your catalog. Teams adopted it quickly. But one question kept coming up: "Why can't I attach documentation to a specific resource? I want my runbook to live on the service, my ADR to live on the domain, my troubleshooting guide to live on the event."

That's exactly what resource-level documentation does.

Documentation that lives with the thing it describes

With resource-level documentation, you can now attach .mdx documentation files directly to any resource in your catalog: services, events, commands, queries, domains, flows, all of it.

The docs live in a docs/ directory alongside the resource, show up in the resource's sidebar, and can be grouped into categories so your teams can find the information they need in the right context.

They're versioned with your resources, so when the schema changes, the ADR changes too. Full audit trail in Git.

What this looks like in practice

Services: runbooks where you actually need them

When something goes wrong at 2am, nobody wants to dig through Confluence to find the deployment runbook for OrdersService. With resource-level documentation, it's right there in the catalog:

services/
  OrdersService/
    index.mdx
    docs/
      runbooks/
        how-to-deploy.mdx
        rollback-procedure.mdx
      guides/
        local-development.mdx

Anyone looking at OrdersService in the catalog sees those docs in the sidebar, directly alongside the service's producers, consumers, and schema. No hunting. No "do you know where the runbook lives?"

Events: the reasoning behind the contract

The people consuming OrderPlaced shouldn't have to guess why the schema looks the way it does. Attach the schema decision record right to the event:

events/
  OrderPlaced/
    index.mdx
    docs/
      adrs/
        why-we-chose-this-schema.mdx
      guides/
        troubleshooting-missing-events.mdx

Now when a consuming team wonders "why is customerId a string and not a UUID here?" the answer is one click away, sitting next to the event definition itself. Context stays with the contract.

Domains: ADRs attached to the bounded context

This one is underrated. Architecture Decision Records are valuable precisely when they're connected to the thing they're about.

An ADR explaining why the Orders domain owns customer address data means nothing floating in a wiki. Attached to the Orders domain in the catalog, it's immediately discoverable by anyone working in or around that domain:

domains/
  Orders/
    index.mdx
    docs/
      adrs/
        why-orders-owns-address-data.mdx
        bounded-context-decision.mdx

The domain page becomes more than a registry entry. It becomes a record of why: why you drew the boundary where you did, why you made those trade-offs, why the model looks the way it does.

More than a catalog

The shift here is subtle but important. EventCatalog has always been a place to discover your architecture. Resource-level documentation makes it a place to understand it too.

Most documentation tools are focused purely on content storage. They have no understanding of your domains, your services, your events, or how everything fits together.

You've probably been in this situation: you're about to make a change, you know there's an ADR about it somewhere, but by the time you find it you've already decided. The docs didn't fail you. The distance did.

So you end up with a documentation page that exists in isolation. Easy to miss, and impossible to stumble across at the right moment.

When documentation is attached to the actual entities in your architecture, it changes how your teams read and use it. An ADR isn't just a decision record, it's a decision record about this domain. A runbook isn't just a guide, it's a guide for this service. The context makes the documentation meaningful.

When a new engineer joins the team, they can open the catalog and not just see what services exist. They can read the deployment guide, the architectural decisions, the troubleshooting runbooks, all in context. When someone is about to consume an event, the design rationale is right there next to the schema.

Documentation that lives in a separate tool gets updated once, then orphaned. Documentation that lives alongside the resource has a much better chance of being found, read, and kept current.

Getting started

Resource-level documentation is available on the Scale plan. To get started, create a docs/ directory alongside any resource and drop in your .mdx files. Subdirectories like adrs/, runbooks/, and guides/ work out of the box for grouping.

Read the resource-level documentation guide to get started and see the full configuration options.

Not on Scale yet? Start a 14-day free trial. No credit card required.

If you have questions or feedback, join us in the EventCatalog Discord. Drop in and let us know what you're attaching where.