Authoring Quick Start

This page gets you writing documentation in under 5 minutes. For full details, follow the links to the reference guides.

What You Need

• Node.js >= 20 installed
• Clone the repo and run cd docusaurus && npm install

Verify your setup:

cd docusaurus && npm run build 2>&1 | tail -3
# Success = 0 "couldn't be resolved" warnings

Where Things Live

What	Where	Edit here?
SRS (requirements)	docs/srs/ + docs/srs/rules/	Yes
SDS (design)	docs/sds/ (domains, rules, reference, traceability)	Yes
STD (tests)	docs/std/	Yes
Guides	docs/guides/	Yes
Frozen v3.0.0 snapshot	versioned_docs/version-3.0.0/	No
Deprecated SDD	docs/sdd/	No

Full layout: Contributor Guide Section 3

Common Tasks

Add or modify an SRS requirement

1. Find the domain file in docs/srs/ (e.g., kitcfg.md)
2. Find the next REQ ID: grep -o "REQ-KITCFG-[0-9]*" docusaurus/docs/srs/kitcfg.md | sort -t- -k3 -n | tail -1
3. Write the requirement using "shall" language with Acceptance Criteria and a Trace block
4. Add the sidebar entry to sidebars.js if it's a new file
5. Run cd docusaurus && npm run build — 0 broken links = done

Format reference: Study srs/filters.md (small domain) or srs/rules/rule-amb.md (rule file). Full format spec: SRS Authoring Guide

Add or modify an SDS design document

1. Find the domain doc in docs/sds/domains/ or docs/sds/rules/
2. Declare the domain character (thin/algorithmic/config-heavy/stateful/integration) in the metadata blockquote
3. Fill mandatory sections (1: Overview, 2: Component Architecture, 8: Implementation Mapping, 9: Design Decisions, 11: Related Documents). Discharge unused sections with standard phrasings — short is correct
4. Update sds-master-index.md if adding a new document or major section
5. Build and verify

Format reference: Study sds/domains/sds-domain-audit.md (config-heavy) or sds/rules/sds-rules-engine.md (algorithmic). Full format spec: SDS Authoring Guide

Convert a Confluence export to SRS

1. Export from Confluence as Word (.docx)
2. Convert: ./docusaurus/scripts/docx2adoc.sh "input/export.docx" "output/export.adoc"
3. Classify every item: "Is this independently testable system behavior?" Yes = Requirement. No = AC, Config Option, UI Detail, or Refinement
4. Consolidate requirement explosion (7 filter variants = 1 filter requirement + ACs)
5. Transform, validate, write to docs/srs/

Full pipeline: Confluence Conversion Guide

Create a version snapshot

When a product release is finalized or a major documentation milestone completes, freeze the current docs into a named version:

cd docusaurus

# 1. Snapshot current docs/ into a versioned directory
npx docusaurus docs:version X.Y.Z
# Creates: versioned_docs/version-X.Y.Z/  and  versioned_sidebars/version-X.Y.Z-sidebars.json
# Updates: versions.json (adds "X.Y.Z" to the array)

# 2. Update docusaurus.config.js — add the new version and set it as default

In docusaurus.config.js, find the docs.versions block and add an entry for the new version. To make it the default (served at /), set lastVersion and assign path: '/':

// docusaurus.config.js → presets → docs
lastVersion: 'X.Y.Z',
versions: {
  current: {
    label: 'Next',
    path: 'next',
  },
  'X.Y.Z': {
    label: 'X.Y.Z',
    path: '/',
  },
  '3.0.0': {            // demote previous default to its own path
    label: '3.0.0',
    path: '3.0.0',
  },
  // older versions...
},

Then build to verify: npm run build 2>&1 | grep -c "couldn't be resolved"

Update (replace) an existing version snapshot

To refresh a frozen version with current docs content:

cd docusaurus

# 1. Remove old snapshot
rm -rf versioned_docs/version-X.Y.Z/
rm -f  versioned_sidebars/version-X.Y.Z-sidebars.json

# 2. Remove from versions.json (edit manually or use jq)
jq 'map(select(. != "X.Y.Z"))' versions.json > versions.tmp && mv versions.tmp versions.json

# 3. Re-snapshot
npx docusaurus docs:version X.Y.Z

# 4. Build and verify
npm run build 2>&1 | grep -c "couldn't be resolved"

No config change needed when replacing — the existing docusaurus.config.js entry still applies.

Full details: Contributor Guide — Version Management

Key Rules

Rule	Details
IDs are immutable	Never change, reuse, or renumber a REQ-* ID
"shall" is mandatory	Every requirement statement must contain "shall"
Classify, don't promote	UI details are never requirements. Config options are never requirements
Short is correct	Sections exist to be discharged, not filled. "No external integrations." is valid content
Every item is traceable	Requirement → Code (code_tags.json) → Test (STD). Both directions must stay in sync
Build is the quality gate	npm run build with 0 broken links. Run before every commit

Validation Checklist

Run these before committing any documentation change:

cd docusaurus

# 1. Build (authoritative — catches broken links)
npm run build 2>&1 | grep -c "couldn't be resolved"  # must be 0

# 2. Mermaid diagrams
bash scripts/validate-mermaid.sh docs              # must be 0 errors

# 3. REQ anchors (idempotent, safe to run)
python scripts/add-req-anchors.py --dry-run        # check for missing anchors

Full validation commands and checklists: Contributor Guide Section 9

Gotchas

• Sidebar is manual — every new file must be added to sidebars.js or it won't appear in navigation
• Blank line before bullets — required for PDF rendering, easy to miss
• fix-docusaurus-links.py is NOT idempotent — git restore before running. add-req-anchors.py IS idempotent.
• SRS filenames don't always match domain codes — audit-log.md not audit.md, user-management.md not usermgmt.md
• Relative links depend on directory depth — docs/srs/ uses ../sds/, but docs/sds/domains/ needs ../../srs/
• Diagrams: quote special chars — pipes, slashes, @, () in Mermaid labels need quotes

Reference Guides

Guide	Use when	Length
Contributor Guide	Repo layout, Docusaurus mechanics, sidebar config, version management, traceability, validation	Comprehensive
SRS Authoring Guide	Writing or modifying requirements — classification taxonomy, document format, operations	Comprehensive
SDS Authoring Guide	Writing or modifying design docs — format, principles, section templates	Moderate
Confluence Conversion Guide	Converting raw Confluence exports into canonical SRS format	Comprehensive
Dev Testing Guide	Behat step definitions, test creation, execution	Comprehensive