ADR-0004: Documentation Restructuring with docs/index.adoc Entry Points

Status

Accepted

Context

The project documentation was primarily contained in README.adoc files at each project root. This created several issues:

  1. README.adoc files became too long: They contained both quick-start information and detailed documentation, making them hard to navigate.

  2. Cross-referencing challenges: References between the umbrella project and sub-projects (like mail-mcp) needed to work in multiple contexts:

    • Local development (files on disk)

    • GitHub rendering (different repositories)

    • Future documentation site generation

  3. No clear documentation entry point: The docs/ directories lacked a central index, making navigation difficult.

  4. Mixed concerns: README files mixed project overview, quick start, detailed documentation, and contributor guidelines.

Decision

Restructure documentation with the following approach:

Minimal README.adoc Files

README.adoc files should contain only:

  • Project title and one-line description

  • Quick start / prerequisites

  • Link to docs/index.adoc for full documentation

  • License reference

docs/index.adoc as Documentation Hub

Each project (umbrella and sub-projects) has a docs/index.adoc that serves as:

  • Main documentation entry point

  • Table of contents for all documentation

  • Links to all ADRs with status

  • Cross-references to related projects

Documentation Structure

maven-mcps/
├── README.adoc              # Minimal: title, project list, link to docs
├── docs/
│   ├── index.adoc           # Main documentation hub
│   ├── adr/                  # Project-wide ADRs
│   ├── external/             # External MCP documentation
│   └── usage/                # Usage guides
└── mail-mcp/
    ├── README.adoc          # Minimal: quick start, link to docs
    └── docs/
        ├── index.adoc       # mail-mcp documentation hub
        ├── adr/             # Project-specific ADRs
        ├── development.adoc
        └── ...

Consequences

Positive

  • Clear separation of concerns: Quick start vs. detailed documentation

  • Better navigation: Central index files in each docs/ directory

  • Scalable structure: Easy to add new documentation without bloating README

  • Foundation for site generation: index.adoc files can serve as navigation roots

Negative

  • One extra click: Users must navigate from README to docs/index.adoc for details

  • Maintenance overhead: Need to keep index files updated when adding docs

Implemented

  • Documentation site generation with Antora (see ADR-0005)

Future Work

  • Implement cross-reference attributes for multi-context rendering

  • Configure GitHub rendering compatibility