notarius/docs/roadmap/documentation.md

Documentation Roadmap

Status

This document captures planned documentation decisions for Notarius. It records policy choices while the application architecture is still being shaped. It does not describe implemented behavior.

Documentation Goals

Notarius documentation should make three boundaries obvious:

• source-format support belongs to input-stage modules;
• extraction-domain behavior belongs to process-stage modules;
• core framework behavior is source-agnostic and domain-agnostic.

Documentation should avoid making the MVP look more transcript-specific or D&D-specific than the architecture intends.

Current Policy Decisions

Planned Work Stays In Roadmap Docs

Until code exists, planned behavior belongs under docs/roadmap/.

Implemented behavior should later move into canonical docs. Roadmap files may then link to those docs or be reduced to remaining future work.

Core Docs Should Use Generic Terms

Core architecture docs should prefer:

• source document;
• source unit;
• source reference;
• input adapter;
• extractor;
• chunker;
• merger;
• normalizer;
• output encoder;
• artifact;
• validator;
• run manifest.

Core docs should avoid transcript-specific terms such as segment, speaker, timestamp, and transcript range unless discussing an input adapter or an example.

Core docs should avoid D&D-specific terms such as spell, NPC, item, combat, and encounter unless discussing process modules, artifact docs, or examples.

Input Module Docs Own Source Formats

Each implemented input-stage module should have a canonical integration document.

Likely future files:

docs/integrations/seriatim-transcript.md
docs/integrations/markdown-source.md

Input module docs should cover:

• accepted external schema or file shape;
• mapping into SourceDocument and SourceUnit;
• metadata preserved by the module;
• validation rules and failure behavior;
• examples.

The Seriatim input module doc should reference the Seriatim schema it supports and explain how transcript segment IDs become source-unit IDs.

Stage Module Docs Own Business Logic

Each implemented stage-module family should have canonical internal or integration docs.

Likely future files:

docs/internal/stage-modules.md
docs/integrations/artifacts-dnd.md

Stage module docs should cover:

• module key;
• stage;
• artifact type;
• schema version;
• required source-reference behavior;
• validator chain;
• prompt and response-schema ownership;
• examples.

D&D concepts should be documented in D&D process-module or artifact docs, not in generic runner or framework docs.

CLI Docs Should Reflect Extensibility

The CLI reference should present input modules, chunk modules, process modules, merge modules, normalize modules, and output modules as selectable or configurable components as they become user-facing.

Provisional command shape:

notarius extract ./source.json --input seriatim --extractors dnd.spells --output ./artifacts.json

Once implemented, docs/cli.md should document:

• positional source input path;
• input module selection;
• process module selection;
• chunk/merge/normalize/output selection when configurable;
• config path behavior;
• output path behavior;
• diagnostics and report behavior;
• exit codes.

Config Docs Should Separate Framework And Plugin-Like Options

docs/config.md should group fields by responsibility:

• input module selection and module-specific options;
• chunk module selection and module-specific options;
• process module selection and module-specific options;
• merge module selection and module-specific options;
• normalize module selection and module-specific options;
• output module selection and module-specific options;
• LLM runtime;
• validation runtime;
• diagnostics.

Module-specific config should not leak into unrelated core config sections.

Examples Should Stay Real

Examples should be added only when the matching behavior exists and should be covered by tests where practical.

Likely future examples:

examples/seriatim-minimal-transcript.json
examples/minimal-config.yml
examples/dnd-spells.artifacts.json

Examples should be secret-free and should use the same command shapes documented in docs/cli.md.

Canonical Documentation Targets

When the first vertical slice is implemented, add or update:

• README.md: concise purpose, shortest useful command, links.
• docs/cli.md: implemented command behavior.
• docs/config.md: implemented config behavior.
• docs/operations.md: diagnostics, retention, failure inspection.
• docs/troubleshooting.md: common failures.
• docs/internal/overview.md: implemented package map.
• docs/internal/pipeline.md: implemented extraction flow.
• docs/internal/stage-modules.md: stage contracts and implemented modules.
• docs/internal/input-modules.md: input adapter contract and implemented input modules.
• docs/internal/validators.md: validator contract and built-ins.
• docs/integrations/seriatim-transcript.md: Seriatim input contract.
• docs/integrations/artifacts.md: output artifact envelope.

Review Checklist For Future Documentation Changes

Before merging docs, check:

• Does the document describe implemented behavior outside docs/roadmap/?
• Are source-format details isolated to input module or integration docs?
• Are D&D details isolated to process module or artifact docs?
• Is there one canonical home for the topic?
• Do command examples match implemented CLI syntax?
• Are examples valid, maintained, and free of secrets?
• Did any architecture, config, CLI, stage module, validator, or artifact contract change require a docs update?