Skip to content

Documentation Guidelines

This guide keeps SkillPilot documentation navigable as QA lanes, curriculum rollout notes, generated reports, and pilot dossiers grow.

Document Roles

Every documentation file should have one primary role.

Role Purpose Typical location Source of truth?
Concept Durable model, semantics, and design intent docs/concept/ Yes
Runbook Operational steps for a repeated workflow near the owning process doc Yes
Process Review rules, status meanings, and decision workflow docs/qa-ci/ or docs/dev/ Yes
Generated status Current computed report, queue, or dashboard artifact docs/qa-ci/status/ No
Pilot or dossier Dated investigation, initial PoC, remediation slice, or one-off evidence bundle docs/qa-ci/archive/, docs/qa-ci/status/, or docs/dev/ No, unless explicitly stated
Implementation note Developer-facing design or migration detail docs/dev/ Sometimes

If a document starts mixing roles, split it before adding more content.

Placement Rules

  • Put durable graph, didactic, runtime, and ontology concepts under docs/concept/.
  • Put QA process contracts, review-lane semantics, and CI rule explanations under docs/qa-ci/.
  • Put generated QA snapshots under docs/qa-ci/status/.
  • Put dated QA investigations under docs/qa-ci/archive/ once they are no longer the current runbook.
  • Put implementation plans, migration notes, and developer-only audits under docs/dev/.
  • Keep temporary experiments out of docs/; use tmp/.

Language

English is the default for documentation. Write a document in German only when its audience is German-specific — German curriculum law, Bundesland rollout content, KI-Verordnung compliance, or coach behaviour that is authored in German because the learner-facing text is German.

  • Do not mix languages inside one document.
  • Learner-facing material that ships in both languages keeps the .de.md / .en.md suffix pair and stays aligned when either side changes.
  • A German document keeps a German title. Index and navigation entries use the document's own language, so a reader can tell before clicking.

mkdocs.yml lists the section index pages plus the durable entry documents per section. It is deliberately not a mirror of the docs tree.

Not listed in the navigation:

  • generated status artifacts under docs/qa-ci/status/
  • dated audits, workboards, and rollout dossiers under docs/dev/
  • compatibility pointer pages that exist only to keep old links working
  • asset-production sources such as comic prompts

These stay reachable through their section index.md, which check:docs-indexes keeps complete. When you add a durable entry document, add it to both the section index and mkdocs.yml. When you add a dated dossier or a generated report, the section index alone is enough.

site_url must point at the host that actually serves the built site (https://enpasos.github.io/skillpilot/). It drives the canonical link tag and sitemap.xml; pointing it at the app domain makes every published page advertise a URL that does not serve documentation.

Generated Files

Generated Markdown files should start with a clear notice:

> Generated artifact. Do not edit manually.
>
> Generated by: `<script>`
> Regenerate with: `<command>`
> Source of truth: `<config-or-ledger>`

Generated files may contain useful human-readable status, but decisions belong in the configured source files, ledgers, mappings, or code that generate them.

Registered generated Markdown files are checked with:

cd app
npm run check:generated-doc-notices

When migrating another generated report to this notice format, add it to app/scripts/generatedMarkdownNoticeRegistry.ts in the same change.

Generated QA status artifacts are also rendered into docs/qa-ci/status/README.md from app/scripts/generatedMarkdownNoticeRegistry.ts. Add new generated status outputs there with their role, source of truth, and regeneration command, then run:

cd app
npm run docs:generated-status-registry
npm run check:generated-status-registry

QA Lane Template

Use this structure for durable QA lane docs:

# <Lane Name>

## Purpose
## Source Of Truth
## Generated Artifacts
## Run
## Blocking Semantics
## Review Ledger
## Review Workflow
## Expansion Criteria
## Related Documents

Keep current counts, sampled findings, and dated investigation notes out of the durable lane doc. Put them in a generated status artifact or an archive/pilot record.

Runbook Template

Use this structure for operational runbooks:

# <Lane Name> Runbook

## Run The Audit
## Inspect Results
## Decide Or Fix An Item
## Interpret Diagnostics
## Verify Local Changes

Runbooks should be short and command-focused. They can link to process docs for semantics instead of restating them.

Pilot And Archive Rules

  • Date PoC records in the filename, for example mem-sparql-consistency-poc-2026-06-01.md.
  • Keep baseline numbers and historical interpretations in the dated record, not in the durable process doc.
  • If an old public link exists, keep a compatibility pointer rather than deleting the file.
  • Archive records should say whether they are historical evidence, current process, or source of truth.

Terminology

The glossary is the source of truth for SkillPilot's core vocabulary. One concept keeps exactly one name, in prose and in identifiers.

Retired synonyms are enforced by CI:

cd app
npm run check:terminology

The rule table lives in app/scripts/checkTerminology.ts. Each rule carries the retired wording, what to write instead, and why the term was dropped, so a failure explains itself.

The check scans what is authored and live. Trees that record what was captured at a point in time — retired landscapes, captured source snapshots, build output — are listed as frozen evidence in the same file and are skipped rather than rewritten.

Hash-pinned packages are not exempt. When a rename touches one, update its wording and its pinned digests in the same change, for example ai/openai-custom-gpt-visible-session/legacy-production-baseline.sha256, and re-run that package's own validator.

When a term is consolidated, add a rule in the same change that renames the occurrences. That keeps the cleanup from having to be repeated later.

Before finishing documentation changes:

git diff --check

Run the repository Markdown link check:

cd app
npm run check:docs-links
npm run check:docs-indexes

Linking Outside The Docs Tree

The published site is rooted at docs/, so a relative link that escapes that tree resolves on GitHub but 404s for site readers. Link repository files outside docs/ through GitHub instead:

[buildFullStandaloneCurriculumPackage.ts](https://github.com/enpasos/skillpilot/blob/main/app/scripts/buildFullStandaloneCurriculumPackage.ts)

Use /blob/main/ for files and /tree/main/ for directories, and percent-encode spaces. check:docs-links resolves both forms back to the filesystem, so these links stay verified, and it fails on any relative link from docs/ that leaves the tree. Paths that are only named, not followed, stay as inline code.

check:docs-indexes currently requires every covered Markdown file to be linked from the corresponding index.md. It covers docs/concept/ recursively and the direct Markdown children of docs/deploy/, docs/dev/, docs/production-pipelines/, docs/qa-ci/, docs/quickstart/, docs/security/, and docs/whitepaper/.

These same checks run in CI. The main ci.yml workflow skips docs-only changes, so .github/workflows/docs_checks.yml runs them for pushes and pull requests that touch only docs/, README.md, AGENTS.md, or mkdocs.yml, and also builds the MkDocs site.

For docs that reference generated JSON, also parse the JSON source files:

node -e "JSON.parse(require('fs').readFileSync('docs/qa-ci/status/curriculum-quality-status.json','utf8')); console.log('json ok')"