Skip to main content

✍️ Contributing to the Docs

How to edit, preview, and ship documentation changes.

:::tip TL;DR

  1. Edit any .md in acesense-docs/**
  2. Preview locally: cd website && pnpm start
  3. Verify before pushing: pnpm test — type-checks and builds the site
  4. Open a PR (or commit directly if you're the owner)
  5. CI runs lint, type-check, build, auth-function tests, links, and freshness :::

🚀 Quick setup​

cd acesense-docs/website
pnpm install
pnpm start   # opens http://localhost:3000 with hot reload

The dev server watches the parent acesense-docs/ folder — any .md edit reloads instantly.

🧭 Where things live​

acesense-docs/
├── intro.md                    # "About these docs" page
├── CONTRIBUTING.md             # (this file)
│
├── get-started/                # Role-based quickstarts
│   ├── _category_.json
│   ├── quickstart.md
│   ├── frontend-dev.md
│   └── ...
│
├── architecture/               # System architecture
├── frontend/                   # Flutter app docs
├── gpu-backend/                # AI pipeline docs
├── firebase-functions/         # Cloud Functions docs
├── admin/                      # Admin panel docs
├── annotate/                   # Annotation tool docs
├── designs/                    # Design system
├── landing/                    # Marketing site docs
├── help/                       # Troubleshooting + common tasks
│
├── reference/                  # Canonical reference material
│   ├── data-model.md
│   ├── glossary.md
│   ├── security.md
│   ├── observability.md
│   ├── testing.md
│   └── cost.md
│
├── decisions/                  # ADRs (Architecture Decision Records)
│   ├── index.md
│   ├── template.md
│   └── NNNN-short-title.md
│
├── runbooks/                   # Incident playbooks
│   └── <symptom>.md
│
└── website/                    # Docusaurus app (don't edit unless theming)
    ├── docusaurus.config.ts
    ├── sidebars.ts
    ├── src/
    │   ├── pages/index.tsx     # Custom homepage
    │   ├── components/
    │   ├── theme/
    │   └── css/custom.css
    └── static/

📝 Frontmatter conventions​

Every markdown file starts with YAML frontmatter:

---
sidebar_position: 1
title: Data Model
sidebar_label: Data Model
last_verified: YYYY-MM-DD
---
FieldPurposeRequired
titleH1 heading shown on the page✅
last_verifiedDate the page was checked against its source of truth✅
sidebar_labelShort label in the sidebar (defaults to title)❌
sidebar_positionOrder within the category (lower = earlier)❌
slugCustom URL path (usually unnecessary)❌
tagsKeywords for search❌

:::warning Never use slug: / twice Only src/pages/index.tsx owns the root route. Don't add slug: / to any markdown file. :::

🎨 Style guide​

Voice​

  • Short, direct, active. "Deploy the function" not "The function should be deployed."
  • Specific over abstract. "Run pnpm build" beats "Build the project."
  • You/your for the reader. "You'll need Python 3.11" not "One needs Python 3.11."
  • Link liberally. Cross-link every mention of a concept to its canonical doc.

Structure every page with​

  1. One-line tagline (quote block at top)
  2. TL;DR admonition — 3-5 bullets a skimmer needs
  3. Main content with H2s as top-level sections
  4. Next Steps footer with 3-5 contextual links

Headings​

  • One H1 per page (the title in frontmatter becomes the H1)
  • H2s = major sections
  • H3s = subsections
  • Never skip levels (no H2 → H4)
  • Avoid emoji in section IDs (they break anchor links)

Code blocks​

  • Always specify the language: ```bash, ```dart, ```typescript
  • Keep examples runnable — copy-paste should work
  • Add comments for non-obvious lines

Tables​

  • Use tables for key/value data, not prose
  • Align columns with :---: for center, :--- for left
  • Keep rows < 80 chars where possible

🧩 Docusaurus features you should use​

Admonitions​

:::tip TL;DR
Quick summary for skimmers.
:::

:::info Tech Stack
Neutral informational block.
:::

:::warning Be careful
Warn readers about footguns.
:::

:::danger Never do this
Critical warnings about destructive actions.
:::

:::note
A side note or context.
:::

Mermaid diagrams​

Wrap Mermaid code in a mermaid fence:

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Do thing]
    B -->|No| D[Skip]
```

Use Mermaid for:

  • Flowcharts (decision trees, pipelines)
  • Sequence diagrams (request/response flows)
  • State diagrams (lifecycles)
  • Entity-relationship (data models)

:::warning Mermaid + headings Don't use H1/H2 Markdown headings inside Mermaid code — they break the parser. :::

Tabs​

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="macos" label="macOS" default>
    `brew install ffmpeg`
  </TabItem>
  <TabItem value="linux" label="Linux">
    `sudo apt install ffmpeg`
  </TabItem>
</Tabs>
  • Use site-relative paths: [Data Model](/reference/data-model), not ../reference/data-model.md
  • Anchor links: [Step 3](/runbooks/job-stuck#step-3--did-the-video-actually-upload)
  • Add context if the link is slow/heavy: [RunPod Console](https://www.runpod.io/console/serverless)
  • Never bare-link in prose (Check https://foo.bar) — wrap it

🔗 Broken link policy​

Docusaurus warns on broken links during pnpm build. Treat warnings as errors.

cd website
pnpm build  # fails on broken links if you run in CI mode

If you reference a page that doesn't exist yet, link to the nearest existing parent page. Create the new page only when you're adding the real content now.

Never leave a dangling [link](/foo/bar) that 404s.

🧪 Local preview checklist​

Before pushing:

  • pnpm start — navigate to every page you touched; visually verify
  • pnpm test — TypeScript clean, build succeeds, and Docusaurus links resolve
  • node ../scripts/check-links.mjs --strict — relative Markdown links resolve
  • node ../scripts/check-freshness.mjs — reviewed pages have an honest date
  • cd ../functions && pnpm test — auth gate and static serving still pass
  • Dark + light mode both look OK (toggle in navbar)
  • Mobile viewport (Chrome DevTools → responsive) doesn't break

🚢 Deploying​

After merge:

cd acesense-docs/website
pnpm build
rm -rf ../functions/site
cp -R build ../functions/site
cd ..
firebase deploy --only functions:docs:docsServer,hosting:docs --project acesense-prod

Rollback via Firebase Console → Hosting → Release history → Rollback.

🆘 Need help?​

  • Docusaurus docs: docusaurus.io/docs
  • Internal: Slack #acesense-dev
  • Existing pages as examples — mimic their structure

Thank you for keeping the docs alive!