Skip to content

Documentation Audit

Last verified: 2026-07-26 against dev at f0388abb.

This audit covers Markdown documentation in the Smart Document Processing repo, excluding vendored dependencies, .git, and generated dependency folders.

Inventory Reviewed

  • Root docs: README.md, CLAUDE.md.
  • Component docs: backend, frontend, extractor apps, Phoenix/Arize, notebooks, smart chunking, and extractor-specific docs.
  • Design docs under docs/design/.
  • Status docs under docs/status/.
  • Script-specific ad hoc operational docs under scripts/adhoc/.

Findings Before Standardization

  • Useful backend, frontend, extractor, Phoenix, and API logical design docs existed.
  • Design docs were explicitly described as "not extensive."
  • Status docs were a historical handoff, not a maintained current status page.
  • The repo had no canonical docs/README.md entrypoint.
  • Product context was scattered between the root README, API design doc, and component READMEs.
  • Diataxis categories were implicit, not explicit.
  • Script-specific operational docs were not indexed from the main docs tree.

Changes Made

  • Added canonical docs home: docs/index.md.
  • Added the repo documentation rules: documentation-standard.md.
  • Added product context pages under product/.
  • Added first-run tutorial under tutorials/.
  • Added task guides under how-to/.
  • Added reference maps under reference/.
  • Added explanation/design context under explanation/.
  • Added runbook index: how-to/runbooks/index.md.
  • Updated docs/design/README.md to become a maintained design index.
  • Updated docs/status/README.md to label historical handoff context and link to maintained product status.
  • Updated the root README to point readers to the standardized docs home.

Remaining Caveats

  • The BYOK LLM key design note is still marked draft in source.
  • Schema/extractor registry updates remain code-defined and can leave stale DB rows if renamed or removed.
  • Backend extractor registry state and deployed Function App infrastructure are separate and must both be updated.
  • Product roadmap and customer-specific release status are not maintained in this repo unless a future owner adds a dedicated roadmap/status process.

Validation

  • Local Markdown link check passed.
  • Whitespace check passed.