📚 Standard Documentation Structure¶
This repository defines a standard, technology-agnostic documentation structure designed to be rendered with MkDocs and published as HTML.
The goal is to provide: - A shared architectural language - Clear development and operational guidelines - Reusable reference architectures - Consistency across teams and platforms
⚠️ Important Operational Note¶
This documentation is for informational purposes and should be kept outside of production CI/CD processes.
No modifications to this repository should trigger restarts, deployments, or automated executions in production environments.
🏛️ Repository design and documentation governance¶
project-with-documentation/
├─ app/ # Application source code (API, WebApp, Worker, etc.)
├─ docs/ # 🌐 Public documentation (no authentication required)
│ # Black-box view: how to use the system
│ # Rendered as a public MkDocs site
├─ docs-private/ # 🔐 Private documentation (authentication required)
│ # White-box view: internal architecture and operations
│ # Rendered as a secured MkDocs site
├─ .dockerignore # Docker ignore rules
├─ .env # Local environment variables (never committed)
├─ .env.sample # Environment variable template
├─ .gitignore # Git ignore rules
├─ README-private.md # 🔐 Private documentation entry point
│ # Used as MkDocs root for docs-private/
├─ README.md # 🌐 Public documentation entry point
└ # Used as MkDocs root for docs/
📂 Documentation Folder Structure (Language-Agnostic)¶
This structure applies to any service type: - API - Web Application - Worker / Background Job - Microservice - Event Consumer / Producer - Batch / Data Processor
The structure documents the what, why, how, and how-to-operate of a service.
docs/
├── README.md
│
├── overview/
│ ├── README.md
│ ├── purpose.md
│ ├── scope.md
│ ├── stakeholders.md
│ └── glossary.md
│
├── architecture/
│ ├── README.md
│ ├── system-context.md
│ ├── logical-architecture.md
│ ├── physical-architecture.md
│ ├── data-flow.md
│ ├── deployment-architecture.md
│ └── architecture-decisions.md
│
├── business-and-requirements/
│ ├── README.md
│ ├── functional-requirements.md
│ ├── non-functional-requirements.md
│ ├── business-rules.md
│ └── use-cases.md
│
├── api-or-interface/
│ ├── README.md
│ ├── contracts.md
│ ├── versioning.md
│ ├── error-handling.md
│ ├── pagination-filtering.md
│ └── examples.md
│
├── data/
│ ├── README.md
│ ├── data-sources.md
│ ├── data-model.md
│ ├── data-validation.md
│ ├── data-quality.md
│ └── data-retention.md
│
├── security/
│ ├── README.md
│ ├── authentication.md
│ ├── authorization.md
│ ├── secrets-management.md
│ ├── threat-modeling.md
│ └── compliance.md
│
├── development/
│ ├── README.md
│ ├── coding-standards.md
│ ├── project-structure.md
│ ├── configuration.md
│ ├── dependencies.md
│ └── local-development.md
│
├── testing-and-quality/
│ ├── README.md
│ ├── testing-strategy.md
│ ├── unit-tests.md
│ ├── integration-tests.md
│ ├── contract-tests.md
│ └── acceptance-criteria.md
│
├── devops-and-deployment/
│ ├── README.md
│ ├── ci-cd.md
│ ├── environments.md
│ ├── infrastructure.md
│ ├── deployment-strategy.md
│ └── rollback-strategy.md
│
├── operations/
│ ├── README.md
│ ├── monitoring.md
│ ├── logging.md
│ ├── alerting.md
│ ├── health-checks.md
│ └── runbooks.md
│
├── performance-and-scalability/
│ ├── README.md
│ ├── performance-requirements.md
│ ├── scalability-strategy.md
│ ├── caching.md
│ └── load-testing.md
│
├── cost-management/
│ ├── README.md
│ ├── cost-estimation.md
│ ├── cost-optimization.md
│ └── capacity-planning.md
│
├── roadmap/
│ ├── README.md
│ ├── mvp-definition.md
│ ├── backlog.md
│ └── future-evolution.md
│
├── risks-and-assumptions/
│ ├── README.md
│ ├── risks.md
│ ├── assumptions.md
│ └── mitigations.md
│
├── changelog/
│ └── README.md
│
├── annexes/
│ ├── README.md
│ ├── references.md
│ └── faq.md
│
└── assets/
├── diagrams/
├── images/
└── files/