Documentation conventions

This folder is both the Rebit / Glass Floor documentation source and the VitePress microsite root (see the root CLAUDE.md for build and deploy commands). This file defines how docs are named, structured, and maintained so the set stays consistent as it grows.

Status: the directory layout, file naming, diagram-asset split, .gitignore rules, and the §3 front-matter header are applied across the tree (front-matter backfilled 2026-07-29). Apply all of them to new docs.

---

1. Directory layout

Docs are organised by type, not by team. Every top-level folder has a single, predictable purpose.

docs/
├── README.md                 # this file — conventions
├── index.md                  # microsite home page
├── .scripts/                 # operational tooling (deploy.sh) — not site content
├── reference/                # evergreen, code-derived truth about the app
│   ├── NN-topic.md
│   └── assets/               # rendered diagrams (*.svg)
│       └── src/              # editable diagram sources (*.drawio)
├── glassfloor/               # the Glass Floor R1 Dell engagement
│   ├── index.md              # engagement home: status, decision log, doc map
│   ├── overview/             # plans and leadership-facing summaries
│   ├── decisions/            # ADR-style design decision records
│   │   └── assets/{,src/}
│   ├── requirements/
│   │   ├── epics/            # point-in-time Jira epic snapshots
│   │   ├── user-stories.md
│   │   └── open-discussions.md
│   └── _sources/             # raw inputs (meeting exports, .docx) — gitignored, not curated docs
└── public/                   # static assets served verbatim by VitePress

Rules

• Type over team. Reference material about the shipping app lives in reference/; engagement material lives under glassfloor/. Do not mix time-bound engagement docs into reference/.
• Raw inputs are quarantined. Meeting exports, .docx, and other unedited source material go in a _sources/ folder (leading underscore = "not a curated doc"). Never leave binary source files loose among finished markdown.
• A decision is recorded once. Each decision lives in exactly one decisions/ record; every other doc (registers, plans, stories) links to it and gets at most a one-line status annotation. The engagement home (glassfloor/index.md) keeps the decision log — add a row there when a decision lands. Superseded text in meeting-record docs is annotated ([SUPERSEDED — <date>] + strikethrough), never silently rewritten.
• One folder, one naming rule (see §2). The rule for a folder is fixed by the table below.

---

2. File naming

Folder	Pattern	Example
reference/	NN-topic.md (zero-padded order prefix, kebab-case)	02-architecture.md
glassfloor/overview/	kebab-case.md	project-plan.md
glassfloor/decisions/	NNNN-slug.md (4-digit ADR number)	0001-pkce-oidc-auth.md
glassfloor/requirements/epics/	E#.#-csgdm-##-slug.md	E1.1-csgdm-31-evocation-welcome.md
glassfloor/requirements/ (other)	kebab-case.md	user-stories.md

Rules

• Lowercase, hyphens, no spaces. No spaces, no _ (except the _sources/ folder marker), no camelCase, no dates in filenames.
• Filenames are self-describing. A reader should know what a file is from its name alone. Epic filenames carry both the human epic label (E1.1) and the Jira ID (csgdm-31) so neither the sidebar nor a reader has to translate.
• Names describe content, not history. A date or version belongs in the front-matter, never the filename.
• ADR numbers are permanent. Once a decision record gets number NNNN, that number is never reused, even if the decision is later superseded.

---

3. Front-matter header

Every markdown doc starts with a YAML front-matter block. This standardises metadata, satisfies the BETSOL governance-header convention, and lets the VitePress sidebar stop hand-labelling files.

---
title: Technical Architecture
status: draft            # draft | in-review | approved | superseded
owner: Chandan Krishna Reddy (BETSOL)
updated: 2026-07-29      # ISO date; the last substantive edit
doc_id: GF-DES-0001      # optional — governance cross-reference ID
supersedes:              # optional — doc_id or path this replaces
---

Rules

• title, status, owner, updated are required on every doc.
• status uses the fixed vocabulary above. A superseded doc keeps its file and links forward to its replacement.
• updated is an absolute ISO date (YYYY-MM-DD), never "last week".
• Home page (index.md) and served HTML in public/ are exempt.

---

4. Diagrams and assets

• Rendered output and source are separated. Each doc folder that needs diagrams gets an assets/ folder for committed .svg (what the site renders) and assets/src/ for editable .drawio sources.
• Reference a diagram by its .svg, not the .drawio.
• Regenerate the SVG whenever you edit the .drawio, in the same commit.
• Never commit editor junk — *.drawio.bkp, .$*.drawio.bkp, .DS_Store are gitignored (see §6).

---

5. Cross-references and the microsite

• Link between docs with relative markdown paths (e.g. [architecture](../reference/02-architecture.md)) so links survive both the raw repo view and the built site.
• Renaming or moving a doc is a three-place edit — update in the same commit:
  1. the root CLAUDE.md documentation index,
  2. the VitePress nav/sidebar in .vitepress/config.mts,
  3. every inbound link from other docs.
• npm run docs:build fails on dead links. Run it before pushing a doc move; a green build is the check that all three places above are consistent.
• With required front-matter title, sidebar entries should reference files by path and let the title carry through, rather than restating a label inline.

---

6. Housekeeping

Add to docs/.gitignore (and untrack anything already committed):

.DS_Store
*.drawio.bkp
.$*.drawio.bkp
**/_sources/

• _sources/ is gitignored, not just quarantined. Raw inputs (.docx, meeting exports) never enter git — prefer linking to the system of record. If a raw file must be shared, use another channel (SharePoint, Slack, email), not the repo.
• Operational scripts do not belong at the docs root among content; they live in docs/.scripts/ (e.g. .scripts/deploy.sh), which VitePress ignores.

---

7. Adding a new doc — checklist

1. Pick the right folder by type (§1).
2. Name it per the folder's pattern (§2).
3. Add the front-matter header (§3).
4. Put diagrams in assets/ (SVG) + assets/src/ (drawio) (§4).
5. Add it to the CLAUDE.md index and the VitePress sidebar (§5).
6. Run npm run docs:build and confirm no dead links (§5).