ADR 0001: Docs-as-Code Standard

Status

Proposed

Context

We need to establish a standard method for capturing, maintaining, and presenting documentation for the Intelligence Cloud Platform. Historically, team wikis (such as Confluence or GitHub Wiki) become detached from code repositories over time, leading to out-of-date information, lack of versioning, and bypass of standard peer review processes.

Decision

We choose the Docs-as-Code pattern. All system documentation, guides, specifications, and architecture decision records will be: 1. Written in standard Markdown (.md). 2. Stored directly inside this git repository under the /documentation directory. 3. Updated in the same Pull Requests (PRs) that introduce the corresponding code modifications. 4. Rendered in developer portals (like Astro Starlight, MkDocs, or Docusaurus) by importing this directory.

Consequences

• Pros: Documentation is versioned along with code branches; reviews are done during PRs; formatting is simple and standardized.
• Cons: Non-technical team members must use Git to edit documentation.
• Follow-up: Setup automatic linting for Markdown links and files in the CI/CD pipeline.