Skip to content

ADR-0013: Module-Local Documentation Structure

Status

Accepted

Date: 2025-11-05

Context

The monorepo had inconsistent documentation organization that made it difficult for contributors to find relevant information and didn't align with modern Python monorepo best practices.

Problems with Previous Structure

  1. Documentation scattered across multiple locations:

  2. Client docs at root docs/ (8 guides + 8 ADRs)

  3. MCP docs split between docs/mcp-server/ (5 files) and katana_mcp_server/ (2 files)

  4. No clear module boundaries

  5. ADRs mixed by scope:

  6. Root docs/adr/ contained client ADRs (001-008, 011-012), MCP ADR (010), and shared ADR (009)

  7. Made it unclear which ADRs applied to which package

  8. Examples not organized by module:

  9. All examples in flat examples/ directory

  10. No separation between client and MCP examples

  11. Difficult to extract packages:

  12. Package-specific docs didn't travel with the package

  13. Would need extensive refactoring to split packages into separate repos

  14. Questions about organization:

  15. "Where are the client docs?" → Unclear (some in root docs/, some might be elsewhere)

  16. "Where are the MCP docs?" → Very unclear (split across 3 locations)
  17. "Which ADRs apply to the client?" → Required reading all ADRs to determine

Decision

We will reorganize documentation into a module-local structure where each package has its own docs/ subdirectory containing all module-specific documentation, including ADRs.

New Structure

katana-openapi-client/
│
├── katana_public_api_client/          # CLIENT PACKAGE
│   ├── [source code...]
│   └── docs/                          # Client-specific docs
│       ├── README.md                  # Navigation/index
│       ├── guide.md                   # User guide
│       ├── testing.md                 # Testing strategy
│       ├── cookbook.md                # Usage recipes
│       ├── CHANGELOG.md               # Release notes
│       └── adr/                       # Client ADRs (001-008, 011-012)
│
├── katana_mcp_server/                 # MCP PACKAGE
│   ├── [source code...]
│   └── docs/                          # MCP-specific docs
│       ├── README.md                  # Navigation/index
│       ├── architecture.md            # MCP architecture
│       ├── development.md             # Development guide
│       ├── deployment.md              # Deployment guide
│       ├── docker.md                  # Docker guide
│       ├── implementation-plan.md     # Implementation roadmap
│       ├── stocktrim-migration.md     # Migration plan
│       └── adr/                       # MCP ADRs (010)
│
├── docs/                              # SHARED MONOREPO DOCS
│   ├── index.md                       # Landing page
│   ├── CONTRIBUTING.md                # Shared contribution guide
│   ├── CODE_OF_CONDUCT.md             # Code of conduct
│   ├── MONOREPO_SEMANTIC_RELEASE.md   # Shared release guide
│   ├── UV_USAGE.md                    # Shared tooling
│   ├── PYPI_SETUP.md                  # PyPI publishing
│   ├── RELEASE.md                     # Release process
│   ├── client/                        # Symlink → ../katana_public_api_client/docs
│   ├── mcp-server/                    # Symlink → ../katana_mcp_server/docs
│   └── adr/                           # Shared/monorepo ADRs (009, 013)
│
└── examples/                          # EXAMPLES
    ├── README.md                      # Examples index
    ├── client/                        # Client examples
    └── mcp-server/                    # MCP examples (placeholder)

Implementation

  1. Created katana_public_api_client/docs/ and katana_mcp_server/docs/ directories
  2. Moved client docs and ADRs to client package
  3. Moved MCP docs and ADRs to MCP package
  4. Reorganized examples by module
  5. Created symlinks from docs/client/ and docs/mcp-server/ to module docs
  6. Updated all internal links and references
  7. Updated mkdocs.yml navigation structure

Consequences

Positive Consequences

  1. Clear Module Boundaries: Each package has complete, self-contained documentation
  2. Improved Discoverability: Easy to find docs - client docs in client package, MCP docs in MCP package
  3. Better ADR Organization: ADRs organized by scope (client/MCP/shared)
  4. Package Extractability: Documentation travels with the package - could extract to separate repo without refactoring
  5. Consistent with Modern Practices: Aligns with Python monorepo best practices
  6. Better mkdocs Integration: Root docs/ aggregates everything via symlinks
  7. Easier Navigation: Clear navigation structure by module in documentation site

Negative Consequences

  1. More Complex Directory Structure: More directories to navigate (though better organized)
  2. Symlinks Required: CI/CD must handle symlinks or copy files for documentation builds
  3. Cross-References: Some documentation cross-references require relative paths (e.g., ../../)

Neutral Consequences

  1. Documentation Paths Changed: All documentation paths updated - old bookmarks/links will break
  2. Git History: File moves preserved in git history but may complicate some git operations

Alternatives Considered

Alternative 1: Keep Flat Structure

  • Description: Keep all docs in root docs/ directory with subdirectories for different topics
  • Pros: Simpler structure, easier to browse all docs at once
  • Cons: Doesn't scale to multiple packages, unclear ownership, difficult to extract packages
  • Why rejected: Doesn't support monorepo evolution and package independence

Alternative 2: Duplicate Documentation

  • Description: Keep docs in both root docs/ and package directories
  • Pros: Easy to find docs in either location
  • Cons: Synchronization nightmare, source-of-truth unclear, duplicated maintenance
  • Why rejected: Unsustainable maintenance burden

Alternative 3: Documentation in Separate Repo

  • Description: Move all documentation to a separate repository
  • Pros: Clean separation, focused documentation repo
  • Cons: Docs far from code, version synchronization issues, harder to keep docs updated
  • Why rejected: Best practice is to keep docs with code

References