Skip to main content

Meta-Analysis: Documentation/Knowledge Structure

Purpose: Synthesize knowledge/documentation structure analysis into comprehensive meta-analysis for "ultimate" canonical docs/documentation structure
Analysis Date: 2025-12-17
Status: COMPLETE
Version: 1.0.0
Part of: E6:S06:T06 – Cross-project meta-analysis and canonical framework design

Executive Summary​

This document provides comprehensive meta-analysis of docs/documentation structures across all 10 analyzed projects (9 client implementations + ai-dev-kit source), synthesizing:

  • Knowledge/documentation structure analysis
  • Pattern frequency tables
  • Convergence/divergence maps
  • Canonical vs legacy matrices

Key Findings:

  • Perfect convergence on docs/ directory naming (100%)
  • Moderate convergence on 5-pillar organization (40%)
  • Strong divergence in organization patterns (5-pillar vs multi-pillar vs hybrid)
  • Moderate adoption of lifecycle metadata (60%)

Data Sources:

  • knowledge-documentation-structure-analysis.md - Granular docs/documentation analysis
  • meta-analysis-pattern-frequency-tables.md - Pattern frequency data
  • meta-analysis-convergence-divergence-maps.md - Convergence/divergence analysis
  • meta-analysis-canonical-vs-legacy-matrices.md - Canonical vs legacy comparison
  • 10 project analysis reports (9 client implementations + ai-dev-kit source)

1. Synthesis: Root Directory Naming​

1.1 Perfect Convergence​

docs/ Directory Naming:

  • Frequency: 100% (10/10 projects)
  • Status: ✅ Perfect convergence
  • Rationale: Clear abbreviation, standard convention, universal adoption

Key Insight: docs/ naming is universal (100%), indicating perfect convergence on ADK canonical.

1.2 Legacy Support Needs​

knowledge/ Directory (Pre-ADK):

  • Frequency: 20% (2/10 projects)
  • Projects: fynd.deals, confidentia (branch 21)
  • Rationale: Pre-ADK structure, Obsidian-friendly
  • Support Strategy: Support knowledge/ during migration to docs/

docs/ Secondary Directory:

  • Frequency: 30% (3/10 projects)
  • Projects: starborn_legacy, fynd.deals, qa-kb
  • Rationale: Supplementary documentation, standard convention
  • Support Strategy: Support docs/ + docs/ hybrid structure during migration

2. Synthesis: Organization Patterns​

2.1 Organization Pattern Convergence​

Pattern 1: ADK Canonical (5-Pillar)

  • Frequency: 40% (4/10 projects)
  • Projects: been-there, dev-toolkit, agentic-ide-rules, ai-dev-kit
  • Structure:
    • Architecture/ - Technical standards, ADRs
    • changelog-and-release-notes/ - Release documentation
    • project-management/ - Project management, Kanban
    • Guides/ - User-facing documentation
    • Documentation/ - Developer documentation (optional)

Pattern 2: Complex Multi-Pillar (15+)

  • Frequency: 10% (1/10 projects)
  • Projects: confidentia (branch 03)
  • Structure: 15+ pillars (Architecture, Customer Enablement, Data, Engineering, Governance, Monitoring, Operations, PM, Product, Security, Testing, Tooling, etc.)

Pattern 3: Hybrid (docs/ + docs/)

  • Frequency: 40% (4/10 projects)
  • Projects: starborn_legacy, free-party-promoter, vwmp, qa-kb
  • Structure: docs/ for main documentation, docs/ for supplementary

Pattern 4: Pre-ADK Custom

  • Frequency: 10% (1/10 projects)
  • Projects: fynd.deals
  • Structure: knowledge/fynd_deals/Kanban/ (pre-ADK structure)

Key Insight: Organization patterns diverge significantly (44% vs 11% vs 44% vs 11%), requiring flexible support.

2.2 Pillar Depth Convergence​

3-Level Default Depth:

  • Frequency: 60% (6/10 projects)
  • Status: ✅ Strong convergence
  • Rationale: Optimal navigation, standard pattern

4-Level Depth:

  • Frequency: 20% (2/10 projects)
  • Projects: confidentia, starborn_legacy
  • Rationale: Complex projects require deeper structure

Key Insight: 3-level depth is standard (67%), but 4-level support needed for complex projects.

3. Synthesis: Document Structure Patterns​

3.1 Frontmatter Convergence​

Frontmatter Presence:

  • Frequency: 90% (9/10 projects)
  • Status: ✅ Strong convergence
  • Rationale: Standard markdown frontmatter, metadata support

Lifecycle Metadata:

  • Frequency: 60% (6/10 projects)
  • Status: ⚠️ Moderate convergence
  • Rationale: ADK lifecycle management, document persistence

Key Insight: Frontmatter is universal (89%), but lifecycle metadata adoption is moderate (67%).

3.2 Document Type Convergence​

Standard Document Types:

  • Frequency: 60% (6/10 projects)
  • Types: Epic, Story, Task, ADR, Guide, Changelog
  • Status: ✅ Moderate convergence

Custom Document Types:

  • Frequency: 30% (3/10 projects)
  • Types: Project-specific types (e.g., UAT, Charter, Spec)
  • Status: ⚠️ Moderate divergence

Key Insight: Standard document types work well (67%), but custom types needed for project-specific needs.

4. Synthesis: Navigation Patterns​

4.1 Navigation File Convergence​

README.md Pattern:

  • Frequency: 78% (7/9 projects)
  • Status: ✅ Strong convergence
  • Rationale: Standard markdown convention, GitHub-friendly

_index.md Pattern:

  • Frequency: 20% (2/10 projects)
  • Projects: fynd.deals, confidentia (some branches)
  • Rationale: Obsidian compatibility, wiki-style navigation
  • Support Strategy: Support both README.md and _index.md

Key Insight: README.md is standard (78%), but _index.md support needed for Obsidian (22%).

4.2 Cross-Referencing Convergence​

Markdown Links:

  • Frequency: 78% (7/9 projects)
  • Format: [Link Text](path/to/file.md)
  • Status: ✅ Strong convergence

Obsidian Links:

  • Frequency: 20% (2/10 projects)
  • Format: [[Link Text]]
  • Projects: fynd.deals, confidentia (some branches)
  • Support Strategy: Support both markdown and Obsidian links

Key Insight: Markdown links are standard (78%), but Obsidian links needed for Obsidian projects (22%).

5. Critical Issues Identified​

5.1 Lifecycle Metadata Adoption (MODERATE)​

Frequency: 67% adoption (6/9 projects)
Impact: Moderate - Lifecycle management not universal
Root Cause: Lifecycle metadata is ADK-specific, not standard markdown

Promotion Strategy:

  1. Document lifecycle benefits
  2. Provide examples and templates
  3. Make lifecycle part of installation
  4. Show automated cleanup benefits

5.2 Organization Pattern Divergence (MODERATE)​

Frequency: 44% vs 11% vs 44% vs 11% (no clear convergence)
Impact: Moderate - Different projects need different structures
Root Cause: Project size/complexity varies significantly

Support Strategy:

  1. Support 5-pillar as canonical (standard projects)
  2. Support multi-pillar extension (enterprise projects)
  3. Support hybrid structure (docs/ + docs/) during migration
  4. Document when to use which pattern

6. Recommendations for "Ultimate" Canonical KB Structure​

6.1 Root Directory​

Recommended: docs/ (Canonical)

  • Format: docs/ (uppercase, abbreviation)
  • Rationale: Perfect convergence (100%), universal adoption
  • Legacy Support: Support knowledge/ during migration

Secondary Directory Support:

  • Hybrid Structure: Support docs/ + docs/ during migration
  • Rationale: 33% of projects use hybrid structure

6.2 Directory Organization​

Recommended: Flexible Pillar Structure

Standard Projects (5-Pillar):

docs/
├── Architecture/                      # Technical standards, ADRs
├── changelog-and-release-notes/      # Release documentation
├── project-management/                 # Project management, Kanban
├── Guides/                           # User-facing documentation
└── Documentation/                    # Developer documentation (optional)

Enterprise Projects (Multi-Pillar Extension):

  • Maintain core 5 pillars as foundation
  • Allow additional pillars (e.g., Security_and_Compliance/, Operations_and_SRE/)
  • Support 15+ pillar structure for complex projects

Legacy Projects (Hybrid):

  • Support docs/ + docs/ hybrid structure during migration
  • Support knowledge/ directory for pre-ADK projects

Rationale:

  • 5-pillar is canonical (44% adoption)
  • Multi-pillar needed for enterprise (11% adoption)
  • Hybrid needed for migration (44% adoption)

6.3 Document Structure​

Recommended: ADK Lifecycle Metadata

Required Fields:

---
lifecycle: evergreen | timeboxed | transient
ttl_days: <integer> | null
created_at: <ISO 8601 datetime>
expires_at: <ISO 8601 datetime> | null
housekeeping_policy: keep | archive | delete
---

Rationale:

  • Lifecycle metadata adoption is moderate (67%)
  • Provides automated document management
  • Supports document persistence classification

Legacy Support:

  • Support documents without lifecycle metadata (33% of projects)
  • Support optional frontmatter during migration

6.4 Navigation​

Recommended: Hierarchical READMEs

Standard Pattern:

  • Root docs/README.md for top-level navigation
  • Section README.md files for each pillar
  • Directory-level README.md files for major subdirectories

Obsidian Support:

  • Support _index.md for Obsidian compatibility
  • Support both README.md and _index.md in same directory

Rationale:

  • README.md is standard (78% adoption)
  • _index.md needed for Obsidian (22% adoption)

6.5 Cross-Referencing​

Recommended: Standard Markdown Links

Format:

  • [Link Text](path/to/file.md) - Standard markdown
  • [[Link Text]] - Obsidian links (for Obsidian projects)

Rationale:

  • Markdown links are standard (78% adoption)
  • Obsidian links needed for Obsidian projects (22% adoption)

7. Summary: "Ultimate" Canonical docs/documentation Structure​

7.1 Root Directory​

  • Name: docs/ (uppercase, abbreviation) - 100% convergence
  • Legacy Support: knowledge/ for pre-ADK projects
  • Hybrid Support: docs/ + docs/ during migration

7.2 Directory Organization​

  • Standard: 5-pillar structure (Architecture, Changelog, PM, Guides, Documentation)
    • Reference Implementation: ai-dev-kit source repository demonstrates perfect 5-pillar canonical structure
  • Enterprise: Multi-pillar extension (15+ pillars)
  • Legacy: Hybrid structure (docs/ + docs/)

7.3 Document Structure​

  • Frontmatter: Required (89% adoption)
  • Lifecycle Metadata: Recommended (67% adoption, promote to 100%)
  • Document Types: Standard types + custom types support

7.4 Navigation​

  • Index Files: README.md (standard), _index.md (Obsidian support)
  • Structure: Hierarchical READMEs at each level

7.5 Cross-Referencing​

  • Format: Standard markdown links [Text](path.md)
  • Support: Obsidian links [[Text]] for Obsidian projects

8. Next Steps​

This docs/documentation structure meta-analysis informs:

  • Ultimate Canonical KB Structure Design (final deliverable)
  • Framework Hardening Recommendations (in good/bad practice catalog)

See Also:

  • knowledge-documentation-structure-analysis.md - Source granular analysis
  • meta-analysis-pattern-frequency-tables.md - Pattern frequency data
  • meta-analysis-convergence-divergence-maps.md - Convergence/divergence analysis
  • meta-analysis-canonical-vs-legacy-matrices.md - Canonical vs legacy comparison

Last Updated: 2025-12-17
Version: 1.0.0
Status: COMPLETE