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 adapters;
• extraction-domain behavior belongs to extractor packages;
• 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;
• 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 extractor packages or examples.

Adapter Docs Own Source Formats

Each implemented input adapter should have a canonical integration document.

Likely future files:

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

Adapter docs should cover:

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

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

Extractor Docs Own Domains

Each implemented extractor family should have canonical internal or integration docs.

Likely future files:

docs/internal/extractors.md
docs/integrations/artifacts-dnd.md

Extractor docs should cover:

• extractor key;
• 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 extractor docs, not in generic runner or framework docs.

CLI Docs Should Reflect Extensibility

The CLI reference should present input adapters and extractors as selectable components.

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 adapter selection;
• extractor selection;
• 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 adapter selection and adapter-specific options;
• extractor selection and extractor-specific options;
• LLM runtime;
• validation runtime;
• source chunking;
• output and diagnostics.

Adapter-specific and extractor-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/adapters.md: adapter contract and implemented adapters.
• docs/internal/extractors.md: extractor contract and built-ins.
• 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 adapter docs?
• Are D&D details isolated to extractor 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, adapter, extractor, validator, or artifact contract change require a docs update?