Skip to main content

Contributing to Documentation

Overview​

This guide establishes standards for creating and maintaining documentation in the CODITECT Cloud Infrastructure repository. Following these standards ensures consistency, navigability, and long-term maintainability.

Documentation Philosophy​

Core Principles​

  1. Documentation is Code - Treat docs with the same rigor as source code
  2. Searchable and Scannable - Use clear headings, tables, and formatting
  3. Self-Contained - Each document should stand alone while linking to related content
  4. Examples Over Explanation - Show working code snippets, not just descriptions
  5. Keep Fresh - Update "Last Updated" dates and remove stale content

Target Audiences​

Always consider your audience when writing:

  • Stakeholders/Executives: High-level overviews, timelines, costs
  • Developers: Code examples, API references, workflows
  • DevOps Engineers: Infrastructure details, deployment procedures
  • Security Auditors: Security architecture, compliance information

Directory Structure​

Categorization​

Documentation is organized into five categories:

docs/
├── architecture/          # C4 diagrams and architecture decisions
├── guides/                # Task-oriented setup and development guides
├── reference/             # Technical specifications and inventories
├── workflows/             # Process flows with sequence diagrams
├── project-management/    # Project plans, tasks, checkpoints
└── *.md                   # Top-level planning and security docs

When to Create a New Document​

CategoryDocument TypeExample
architecture/System design, C4 diagrams, ADRsc1-system-context.md, ADR-001-use-fastapi.md
guides/How-to guides, setup proceduresgcp-setup.md, DEPLOYMENT-GUIDE.md
reference/Specifications, inventories, schemasgcp-infrastructure-inventory.md, API-REFERENCE.md
workflows/Sequence diagrams, process flowslicense-acquisition-workflow.md
project-management/Plans, tasks, checkpointsproject-plan.md, tasklist.md
docs/ (root)High-level planning, securitycritical-path-analysis.md, SECURITY.md

Markdown Standards​

File Naming​

Use kebab-case with descriptive names:

  • ✅ gcp-infrastructure-inventory.md
  • ✅ user-registration-flow.md
  • ✅ c1-system-context.md
  • ❌ gcp_inventory.md
  • ❌ flow1.md

README files in each directory:

  • Each subdirectory MUST have a README.md with navigation index

Document Structure​

Every document should include:

# Document Title

## Overview (or Executive Summary)
[1-3 paragraphs explaining purpose, scope, and audience]

## [Main Sections]
[Organized logically with clear headings]

## Related Documentation
[Links to related docs]

---

**Last Updated:** YYYY-MM-DD
**Status:** [Complete/In Progress/Planned]
**Owner:** [Team/Person]

Heading Hierarchy​

Use proper heading levels:

# H1 - Document Title (only one per document)
## H2 - Major sections
### H3 - Subsections
#### H4 - Details (use sparingly)

DO NOT skip levels:

  • ✅ H1 → H2 → H3
  • ❌ H1 → H3 (skips H2)

Code Blocks​

Always specify language for syntax highlighting:

✅ Good:
    ```python
    def hello():
        print("Hello, World!")
    ```

❌ Bad:
    ```
    def hello():
        print("Hello, World!")
    ```

Common languages:

  • python, bash, yaml, hcl (Terraform), sql, json, dockerfile

Tables​

Use tables for structured data:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |

Align numerical values right:

| Service | Monthly Cost |
|---------|--------------|
| GKE     |        $100  |
| Cloud SQL|       $150  |

Use relative paths for internal docs:

✅ Good: [Architecture](architecture/c1-system-context.md)
❌ Bad:  [Architecture](/docs/architecture/c1-system-context.md)
❌ Bad:  [Architecture](https://github.com/.../c1-system-context.md)

Use descriptive link text:

✅ Good: See the [GCP Setup Guide](guides/gcp-setup.md) for details
❌ Bad:  See [here](guides/gcp-setup.md) for details

Lists​

Use consistent formatting:

Unordered lists:

- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2
- Item 3

Ordered lists:

1. First step
2. Second step
3. Third step

Checkbox lists (for tasks):

- [x] Completed task
- [ ] Pending task

Diagrams​

Mermaid Syntax​

Use GitHub-compatible Mermaid:

Sequence Diagrams:

    ```mermaid
    sequenceDiagram
        participant User
        participant API
        User->>API: Request
        API-->>User: Response
    ```

Gantt Charts:

    ```mermaid
    gantt
        title Project Timeline
        dateFormat YYYY-MM-DD

        section Phase 1
        Task 1 :done, t1, 2025-11-20, 3d
        Task 2 :active, t2, after t1, 2d
    ```

Flowcharts:

    ```mermaid
    flowchart TB
        A[Start] --> B{Decision}
        B -->|Yes| C[Do This]
        B -->|No| D[Do That]
    ```

Diagram Best Practices​

  1. Test on GitHub - Verify diagrams render correctly
  2. Keep it simple - Max 10-12 nodes per diagram
  3. Use clear labels - Descriptive text, not abbreviations
  4. Add legend if needed - Explain symbols or colors

Content Standards​

Writing Style​

Use clear, concise language:

  • ✅ "Deploy the application to GKE using kubectl"
  • ❌ "The application should be deployed to the GKE cluster utilizing the kubectl command-line tool"

Use imperative mood for guides:

  • ✅ "Run the following command"
  • ❌ "You should run the following command"

Use present tense for descriptions:

  • ✅ "The API validates JWT tokens"
  • ❌ "The API will validate JWT tokens"

Code Examples​

Provide copy-paste ready snippets:

✅ Good:
    ```bash
    gcloud container clusters get-credentials coditect-citus-dev \
      --region us-central1 --project coditect-citus-prod
    kubectl get nodes
    ```

❌ Bad:
    ```bash
    gcloud container clusters get-credentials <cluster-name> \
      --region <region> --project <project-id>
    kubectl get nodes
    ```

Include expected output:

    ```bash
    kubectl get nodes
    # Expected output:
    # NAME                          STATUS   ROLES    AGE   VERSION
    # gke-cluster-pool-1-abc123     Ready    <none>   5d    v1.28.3
    ```

Cross-References​

Link liberally to related documents:

For deployment instructions, see [implementation-roadmap.md](implementation-roadmap.md).

Related workflows:
- [User Registration](workflows/user-registration-flow.md)
- [License Acquisition](workflows/license-acquisition-workflow.md)

Add "Related Documentation" section at bottom:

## Related Documentation

### Architecture
- [c1-system-context.md](architecture/c1-system-context.md)
- [c2-container-diagram.md](architecture/c2-container-diagram.md)

### Guides
- [gcp-setup.md](guides/gcp-setup.md)
- [local-development.md](guides/local-development.md)

Metadata​

Every document should end with:

---

**Last Updated:** 2025-11-23
**Status:** Complete
**Owner:** AZ1.AI INC

Status values:

  • Complete - Document finished and reviewed
  • In Progress - Actively being written
  • Planned - Placeholder for future content
  • Deprecated - No longer relevant (explain why)

Specific Document Types​

Architecture Documents (C4 Model)​

C1 - System Context:

  • Purpose and scope
  • External actors and systems
  • High-level interactions
  • Cost estimates

C2 - Container Diagram:

  • All application containers
  • Technology choices
  • Communication patterns
  • Deployment architecture

C3 - Component Diagram:

  • Internal component structure
  • Interfaces and dependencies
  • Data flows

ADRs (Architecture Decision Records):

# ADR-NNN: Title

## Status
[Proposed/Accepted/Deprecated]

## Context
[Why is this decision needed?]

## Decision
[What did we decide?]

## Consequences
[What are the implications?]

## Alternatives Considered
[What else did we evaluate?]

Workflow Documents​

Required sections:

  1. Overview - Purpose and scope
  2. Sequence Diagram - Mermaid diagram showing flow
  3. Implementation Details - Code examples
  4. Error Handling - Failure scenarios
  5. Test Cases - How to verify
  6. Implementation Time - Realistic estimate

Guide Documents​

Required sections:

  1. Prerequisites - Required tools and access
  2. Time Required - How long this takes
  3. Step-by-Step Instructions - Numbered steps with commands
  4. Verification - How to confirm it worked
  5. Troubleshooting - Common errors and solutions

Reference Documents​

Required sections:

  1. Overview - What this reference covers
  2. Specifications - Detailed technical information
  3. Quick Reference Tables - Scannable data
  4. Examples - Concrete use cases

Review Process​

Before Submitting​

Checklist:

  • Document follows naming conventions
  • Headers use proper hierarchy (H1 → H2 → H3)
  • Code blocks specify language
  • Links use relative paths
  • Mermaid diagrams render on GitHub
  • Cross-references to related docs added
  • "Last Updated" date is current
  • No broken links
  • README.md updated if new file added

Pull Request Guidelines​

PR title:

docs: Add C3 component diagram for License API

PR description:

## What
Add detailed component diagram for License API internals.

## Why
Developers need to understand internal architecture before implementing endpoints.

## Changes
- Created `docs/architecture/C3-LICENSE-API-COMPONENTS.md`
- Updated `docs/architecture/README.md` with link
- Added cross-references from C2 diagram

## Checklist
- [x] Mermaid diagram renders correctly
- [x] All links work
- [x] README updated

Review Criteria​

Reviewers should check:

  1. Accuracy - Technical content is correct
  2. Completeness - No missing sections
  3. Clarity - Easy to understand
  4. Consistency - Matches existing docs style
  5. Navigation - Proper cross-references
  6. Freshness - "Last Updated" is current

Maintenance​

Keeping Docs Fresh​

Regular audits:

  • Monthly review of "Last Updated" dates
  • Quarterly link validation
  • Annual full content review

Update triggers:

  • Infrastructure changes → Update reference docs
  • Architecture changes → Update C1-C3 diagrams
  • New features → Update workflows and guides
  • Security issues → Update security docs

Deprecating Documents​

If a document is no longer relevant:

  1. Add [DEPRECATED] to title
  2. Add deprecation notice at top: 
    > **DEPRECATED:** This document is no longer maintained.
    > See [NEW-DOCUMENT.md](NEW-DOCUMENT.md) instead.
  3. Update status to Deprecated
  4. Remove from navigation READMEs
  5. After 6 months, move to docs/archive/

Tools and Automation​

Markdown editors:

  • VSCode with Markdown Preview
  • Typora
  • Mark Text

Linting:

  • markdownlint - Markdown style checking
  • markdown-link-check - Verify links

Diagram testing:

Automation (Future)​

Planned:

  • GitHub Actions to check broken links
  • Automated "Last Updated" date insertion
  • Diagram validation in CI/CD
  • Auto-generated README indexes

Examples​

Good Documentation Examples​

In this repository:

Common Mistakes​

Avoid these:

  • ❌ No "Last Updated" date
  • ❌ Broken internal links
  • ❌ Code blocks without language specified
  • ❌ Skipping heading levels (H1 → H3)
  • ❌ Using absolute URLs for internal docs
  • ❌ No cross-references to related docs
  • ❌ Mermaid diagrams that don't render on GitHub

Questions?​

For documentation questions:

  • Review existing docs in this repo
  • Check README.md for navigation
  • Ask in pull request reviews

For technical questions:

  • See specific guide or reference document
  • Check workflow diagrams for process flows

Last Updated: 2025-11-23 Status: Complete Owner: AZ1.AI INC