Skip to content

ADR-0009: Config Platform Documentation Migration

  • Status: accepted
  • Deciders: ConnectSoft Architecture Team
  • Date: 2025-12-17

Context and Problem Statement

Config Platform documentation (External Configuration System - ECS) currently exists in ConnectSoft.Documentation/Docs/saas/. This documentation includes vision, business requirements, architecture blueprints, solution architecture, and backlog planning documents that describe the Config Platform as a reusable SaaS product. The documentation should be discoverable alongside other platform documentation in CompanyDocumentation.

The question: Where should Config Platform documentation be located to ensure proper categorization, discoverability, and alignment with the overall documentation structure?

Decision Drivers

  • Need for centralized documentation location
  • Requirement for proper categorization (@saas, @product-portfolio, @config-platform)
  • Need for improved discoverability of platform documentation
  • Requirement for consistency with existing documentation structure
  • Need to organize multiple related documents for a single platform
  • Alignment with existing Config Platform overview document

Considered Options

Option 1: Keep in ConnectSoft.Documentation

Approach: Leave documentation in the original location.

Pros:

  • No migration effort required
  • Existing links remain valid

Cons:

  • Documentation scattered across repositories
  • Difficult to discover alongside other platform docs
  • Inconsistent with centralized documentation approach
  • Missing proper categorization tags
  • No clear relationship to existing Config Platform overview

Rejected - Does not meet discoverability and categorization requirements.

Option 2: Migrate to CompanyDocumentation under docs/product-portfolio/platforms/config-platform/ (Selected)

Approach: Migrate documentation to ConnectSoft.CompanyDocumentation/docs/product-portfolio/platforms/config-platform/ with appropriate categorization and subdirectory organization.

Pros:

  • Centralized documentation location
  • Proper categorization with @saas, @product-portfolio, and @config-platform tags
  • Clear organization with subdirectory structure for multiple documents
  • Improved discoverability in navigation
  • Consistent with existing platform documentation structure
  • Aligns with existing Config Platform overview document
  • Follows pattern of other platform documentation (e.g., domain blueprints have subdirectories)

Cons:

  • Migration effort required
  • Potential broken links (if any external references exist)
  • Need to update navigation

Decision

Migrate Config Platform documentation from ConnectSoft.Documentation/Docs/saas/ to ConnectSoft.CompanyDocumentation/docs/product-portfolio/platforms/config-platform/:

Migrated Files:

  • external-configuration.md → 00-overview.md - Main overview document
  • external-configuration-vision.md → vision.md - Vision document
  • external-configuration-brd.md → business-requirements.md - Business Requirements Document
  • external-configuration-architecture-blueprint.md → architecture-blueprint.md - Enterprise Architecture blueprint
  • external-configuration-solution-architecture.md → solution-architecture.md - Solution Design Document
  • external-configuration-plan.md → backlog-plan.md - Backlog planning cycles

Categorization:

  • Add product-portfolio and config-platform tags to all migrated documents
  • Maintain existing tags (saas, architecture, brd, vision, etc.)
  • Update titles for consistency (e.g., "Config Platform - Vision" instead of "External Configuration System - Vision")

Navigation:

  • Update existing Config Platform entry in mkdocs.yml to include detailed documentation subdirectory
  • Update existing config-platform.md overview to reference detailed documentation

Rationale

  • Centralization: Single source of truth for all company documentation improves maintainability and discoverability.
  • Categorization: Proper tags enable better search and filtering of platform documentation.
  • Organization: Subdirectory structure allows organizing multiple related documents for a single platform, following the pattern of domain blueprints.
  • Discoverability: Platform documentation is now accessible alongside other platform documentation in the navigation.
  • Consistency: Aligns with existing documentation structure and categorization patterns.
  • Alignment: Works with existing Config Platform overview document, enhancing rather than replacing it.

Consequences

Positive Consequences

  • Centralized documentation location
  • Improved discoverability and navigation
  • Proper categorization with appropriate tags
  • Clear organization with subdirectory structure for multiple documents
  • Consistent documentation structure
  • Better alignment with product portfolio organization
  • Enhanced existing overview document with links to detailed documentation

Negative Consequences

  • Migration effort required (completed)
  • Potential broken external links (if any exist, need to be updated)
  • Need to maintain navigation structure
  • Multiple documents to maintain (but better organized)