Contributing Documentation¶

This guide explains how to add your service's documentation to the internal docs hub.

Overview¶

We use a "push-based" model: each service repo pushes its /docs folder to the central hub automatically when changes merge to main.

flowchart TB
    subgraph Your Repo
        A[/docs folder]
    end
    subgraph GitHub Actions
        B[push-docs.yml]
    end
    subgraph Central Hub
        C[internal-docs repo]
        D[mkdocs build]
    end
    subgraph Live Site
        E[internal.bvrstco.com]
    end

    A -->|On merge to main| B
    B -->|Copies to| C
    C --> D
    D --> E

Step 1: Create Your Docs Folder¶

In your service repo, create a /docs folder with at least an index.md:

your-repo/
├── src/
├── docs/
│   ├── index.md          # Required: Landing page
│   ├── getting-started.md
│   ├── api-reference.md
│   └── assets/           # Optional: Images
│       └── diagram.png
└── ...

Required: index.md¶

Your index.md should include:

# Service Name

Brief description of what this service does.

## Quick Links

- [Getting Started](getting-started.md)
- [API Reference](api-reference.md)

## Overview

More detailed explanation of the service...

Step 2: Add the Push Workflow¶

Copy the workflow template to your repo:

.github/workflows/push-docs.yml

name: Push Docs to Central Hub

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'

jobs:
  push-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: cpina/github-action-push-to-another-repository@main
        env:
          API_TOKEN_GITHUB: ${{ secrets.CENTRAL_DOCS_TOKEN }}
        with:
          destination-github-username: 'bvr-str'
          destination-repository-name: 'internal-docs'
          source-directory: 'docs'
          target-directory: 'docs/services/YOUR-REPO-NAME'  # ← Update this
          target-branch: 'main'
          commit-message: 'docs: sync from ${{ github.repository }}'
          user-email: github-actions[bot]@users.noreply.github.com
          user-name: github-actions[bot]

Update the target directory

Replace YOUR-REPO-NAME with your actual repo name (e.g., coordinator-backend).

Step 3: Add the Secret¶

Your repo needs the CENTRAL_DOCS_TOKEN secret to push to the central hub.

Ask a team lead for the token value
Go to your repo → Settings → Secrets → Actions
Add secret: CENTRAL_DOCS_TOKEN

After your first push, ask a maintainer to add your service to the navigation.

They'll update two files in internal-docs:

mkdocs.yml — sidebar navigation
docs/services/index.md — service list

Writing Tips¶

Use Mermaid for Diagrams¶

You can add diagrams directly in Markdown:

```mermaid
flowchart LR
    A[Request] --> B[Auth]
    B --> C[Handler]
    C --> D[Response]
```

Use Admonitions for Callouts¶

!!! info "Note Title"

    This is an informational callout.

!!! warning "Caution"

    This warns the reader about something.

Link to Other Docs¶

See the [Architecture Guide](../guides/architecture.md) for more context.

FAQ¶

Q: How long until my changes appear?

A: Within 2-3 minutes of merging to main.

Q: Can I preview locally?

A: Yes! Run mkdocs serve in your /docs folder (requires pip install mkdocs-material).

Q: What if I only want to update docs without changing code?

A: Just edit files in /docs and merge. The workflow only triggers on /docs changes.