docs: consolidate and restructure documentation for improved navigation#59
Merged
docs: consolidate and restructure documentation for improved navigation#59
Conversation
Major documentation reorganization reducing file count from 77 to 47 (39% reduction) while improving discoverability and cross-referencing. Consolidates scattered content into themed groups and establishes comprehensive ADR coverage for architectural decisions.
Key changes:
- ADR expansion: Added 8 new Architecture Decision Records (ADR 0003-0010) covering capability-based auth, dual database support, transaction management, rate limiting, API versioning, Gin framework choice, UUIDv7, and Argon2id
- API restructuring: Organized API docs into themed directories (auth/, data/, observability/) and created unified fundamentals page for cross-cutting concerns (errors, capabilities, rate limits, versioning)
- Operations consolidation: Merged deployment, security, observability, KMS, and runbook content into focused hierarchies
- Content consolidation: Merged development guides, operator quick references, incident playbooks, and versioned examples into parent documents
- Getting started simplification: Combined day-0 operator/developer walkthroughs into single unified guide
- Release history: Consolidated historical release notes and upgrade guides into single RELEASES.md file
- Documentation metadata: Updated version to 0.8.0, fixed all cross-references, updated PR template and markdownlint config
Migration notes:
- All API documentation moves from docs/api/ to themed subdirectories
- Operations guides now under operations/{deployment,kms,observability,runbooks,security}
- CLI commands moved from docs/cli/commands.md to docs/cli-commands.md
- Configuration consolidated from docs/configuration/environment-variables.md to docs/configuration.md
- Glossary merged into architecture concepts document
- Docs changelog removed (project CHANGELOG.md now covers all changes)
All cross-references updated to reflect new structure with backward-compatible anchors preserved where possible.
Update CI workflow and Python check scripts to reflect the documentation restructure that consolidated files and moved content into themed subdirectories.
During the documentation reorganization (77→47 files), RELEASES.md was created as a consolidated file containing all 10 historical release notes (v0.1.0 - v0.8.0). The CI release checker treated all versions as "new" and attempted to validate each against the compatibility matrix, which intentionally only covers recent releases (v0.4.0+). This caused validation failures for historical versions.
allisson
force-pushed
the
update-docs
branch
from
f1aa62c to
e405947
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Major documentation reorganization reducing file count from 77 to 47 (39% reduction) while improving discoverability and cross-referencing. Consolidates scattered content into themed groups and establishes comprehensive ADR coverage for architectural decisions.
Key changes:
Migration notes:
All cross-references updated to reflect new structure with backward-compatible anchors preserved where possible.