docs-builder
Loading

Distributed documentation

Distributed documentation is the architectural approach that allows repositories to build their own documentation independently.

The separation between building individual documentation sets and assembling them enables distributed builds, where:

  • Each repository builds its own documentation independently.
  • Builds don't block each other.
  • Teams maintain full autonomy over their documentation.
  • Cross-repository links are validated without requiring synchronized builds.

Each time a documentation set is built successfully on its default integration branch, it produces and publishes a links.json file (Link Index) to a central location (Link Service).

This Link Index contains all the linkable resources in that repository at that specific commit.

For instance, Elasticsearch's links.json represents all linkable resources in the Elasticsearch repository's main branch.

This distributed approach provides several key advantages:

  • Outbound links: Validate links to other repositories ahead of time, even during local docs-builder builds.
  • Inbound links: Know when changes to your documentation would break links from other repositories.
  • Isolation: Documentation errors in one repository won't affect builds of other repositories.
  • Fallback mechanism: When a repository has build failures on its integration branch, the assembler falls back to the last known good commit.
  • Snapshot builds: Assembled builds only use commits that successfully produced a Link Index.
  • Teams can iterate on their documentation independently.
  • No coordination required for routine updates.
  • Faster feedback loops for documentation changes.

The distributed documentation system relies on several key components:

Even during local development, docs-builder can access the Link Service to validate cross-repository links without requiring you to clone and build all related repositories.