📦 Project with Documentation – Template Overview¶
This repository provides a ready-to-use project template that demonstrates how to structure:
- Application source code
- Public documentation
- Private (authenticated) documentation
- MkDocs-based documentation sites
- Reusable project scaffolding
It is intended to be used as a reference and starting point for development teams.
📚 Table of Contents¶
📌Note: It is recommended that each developer create a README.md file in their repo code with the table of contents to the files, serving as an index like index.html. This way, when converted to HTML using mkdocs, it is not necessary to manage menus for each repo; instead, each repo manages its own menu like a landing page.
📖 Documentation¶
- 🌐 Public Documentation
- 🔐 Private Documentation
- 🔐 Private Documentation / lifecycle
- 🧾 About | Component metadata, ownership, public/private links
- ❗ Required - About section with public/private links to technical and functional documentation, ownership info
- All code in production must be documented, at least including the location of its repository (Azure DevOps / Github).
⚠️ 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.
trigger:
branches:
include:
- main
paths:
include:
- Microservice/*
exclude:
- Microservice/docs/**
- Microservice/docs-private/**
- Microservice/*.md
- '*.md' # root path
📦 Templates¶
🏛️ Documentation repository and governance design template¶
# 📁 Project Documentation Structure
```text
project/
│
├─ app/ # Application source code (API, Worker, WebApp, etc.)
│
├─ docs/ # 🌐 Public documentation (no authentication required)
│ │ # Black-box view: how to use the system
│ │ # Rendered as a public MkDocs site
│ │
│ ├─ about.md # [Required] Component metadata, public reference property - Not confidential
│ | # The about.md content must be exposed through a runtime-accessible endpoint or page,
│ | # enabling identification of the component, ownership, repositories, and documentation links.
│ │
│ ├─ overview/
│ │ ├─ README.md # General component overview
│ │ └─ authentication.md # Public authentication details
│ │
│ ├─ api/
│ │ ├─ endpoints.md # Public API endpoints
│ │ └─ errors.md # Public error catalog
│ │
│ └─ usage/
│ └─ getting-started.md # Getting started guide
│
├─ docs-private/ # 🔐 Private documentation (authentication required)
│ │ # White-box view: internal architecture & operations
│ │ # Rendered as a secured MkDocs site
│ │
│ ├─ about.md # [Required] Component metadata, internal reference property - Confidential
│ | # The about.md content must be exposed through a runtime-accessible endpoint or page,
│ | # enabling identification of the component, ownership, repositories, and documentation links.
│ │
│ ├─ architecture/
│ │ └─ system-overview.md # Internal architecture overview
│ │
│ ├─ business-logic/
│ │ └─ rules.md # Business rules
│ │
│ ├─ data/
│ │ └─ queries.md # Queries and data access
│ │
│ ├─ lifecycle/ # Technology Lifecycle Declaration (TLD)
│ │ └─ technology-lifecycle.md # Every component MUST declare its Technology Lifecycle
│ │
│ ├─ security/
│ │ └─ jwt-validation.md # Security implementation details
│ │
│ └─ operations/
│ └─ runbooks.md # Operational runbooks
│
├─ .dockerignore # Docker ignore rules
├─ .env.sample # Environment variable template
├─ .gitignore # Git ignore rules
├─ README.md # 🌐 Public documentation entry point (MkDocs root)
└─ README-private.md # 🔐 Private documentation entry point (MkDocs root)