Skip to main content

Writing documentation

This site is a Docusaurus project in the emaw-documentation repository. Pages are MDX files under docs/. Anyone on the team can edit a page with the Edit this page link at the bottom, or by cloning the repo.

Run it locally​

git clone https://github.com/Every-Man-A-Warrior/emaw-documentation.git
cd emaw-documentation
npm install
npm start          # http://localhost:3000, hot reload
npm run build      # production build; fails on broken links
npm run typecheck  # TypeScript check for src/

Node 20 or newer is required (engines in package.json). The team standard is Node 26 via nvm.

Where things go​

FolderAudienceSidebar
docs/developer/EngineersDeveloper Guide
docs/user/Staff and end usersUser Guide

Both sidebars are generated from the folder tree (sidebars.ts). Each folder has a _category_.json that sets its label and position; each page sets sidebar_position in its front matter. Lower numbers sort first.

docs/developer/backend/_category_.json
{
  "label": "Backend (Django)",
  "position": 40,
  "link": {"type": "generated-index"}
}

Front matter​

---
title: Local development
sidebar_position: 3
description: One sentence used in search results and generated index cards.
---

title becomes the H1, so do not repeat it as a # heading in the body.

Page templates​

Developer page​

  1. What this is: one or two sentences.
  2. Where it lives: repo and key paths, using <RepoLink>.
  3. How it works: prose, a table, or a Mermaid diagram.
  4. How to run or change it: commands in fenced blocks.
  5. Gotchas: admonitions for anything that bites.

User Guide page​

  1. What it is for
  2. Before you start: access, sign-in, prerequisites.
  3. Steps: numbered, one action per step, a <Screenshot> after the step it illustrates.
  4. Tips and troubleshooting

Components​

These are registered globally in src/theme/MDXComponents.tsx, so no import is needed.

Screenshot​

A slot for an image. While src is empty it renders a labelled placeholder, so guides can be written before the screenshots exist.

<Screenshot
  caption="The Contacts list with the filter bar open"
  todo="Capture on admin-dev with the Region filter expanded"
/>

<Screenshot caption="Quiet Time journal" mobile />

<Screenshot caption="The Contacts list" src="/img/screenshots/crm-contacts.png" />
Example placeholder (this is what a pending screenshot looks like)

Put real images under static/img/screenshots/<app>/ and name them after the page and state, for example crm-contacts-filter-open.png. Prefer PNG for UI, keep the browser at 1440 px wide for desktop apps, and crop out personal data: the dev database contains real people.

Links into a repository at its development branch.

<RepoLink repo="emaw-django-app" path="docs/CRM_FRONTEND_GUIDE.md" />
<RepoLink repo="emaw-crm-app" path="src/features/" />
<RepoLink repo="emaw-website">the website repo</RepoLink>

Renders: docs/CRM_FRONTEND_GUIDE.md

Mermaid diagrams​

Fenced ```mermaid blocks render as diagrams.

Admonitions​

:::warning
The dev database holds real contacts. Never enable campaign sending against it.
:::

Use note, tip, info, warning and danger.

Rules​

  • Never write secret values. Environment variables are referenced by name only. Stripe test card numbers are fine; everything else that unlocks something is not.
  • Link, do not copy, volatile detail. API contracts, per-app runbooks and setup checklists live in their repositories next to the code. Summarise here and link with <RepoLink>.
  • Say which environment. Every URL, hostname or command should make clear whether it is dev or production.
  • Keep the build green. npm run build must pass before you commit. Broken internal links fail the build.
  • One topic per page. If a page needs more than three H2 sections of unrelated material, split it.