175 lines
5.0 KiB
Markdown
175 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
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?
|