Documentation Governance

This page defines the minimum quality bar and release-time controls for ta4j documentation.

Documentation quality bar

User-facing documentation should satisfy:

Coverage: installation, strategy building, backtesting, live operations, and troubleshooting are all documented with runnable references
Clarity: canonical paths and decision points are explicit
Operability: production checklists and failure handling are documented
Discoverability: key pages are reachable from Home and _Sidebar
Freshness: docs remain aligned with current APIs and examples

4.5 bar policy:

Scores at >=4.5 must be supported by explicit evidence in the rubric’s evidence contract.
Score updates must include a short justification note tied to changed artifacts/checks.

Home.md: canonical wiki homepage source
README.md: repository landing page copy generated verbatim from Home.md via scripts/sync-readme-from-home.sh
ta4j-examples/README.md: runnable progression and example discovery
Wiki:
- Canonical User Journey: end-to-end flow
- Backtesting, Live Trading: execution usage guidance
- Live Trading Runbook, Backtesting Realism Checklist, Troubleshooting Hub: production operations

Owner roles:

Feature author owns doc updates for changed APIs/examples in the same change set.
Release reviewer enforces the release-note-to-docs delta checklist.
Maintainer on duty refreshes scorecard and freshness status before a release cut.

Homepage sync workflow:

Edit Home.md directly.
Run bash scripts/sync-readme-from-home.sh before commit to refresh README.md.
CI re-runs the sync script and fails if committed README.md is out of date.

Release preparation must validate:

Automation:

scripts/docs-integrity-check.sh (in the ta4j repository)
prepare-release.yml runs this check before versioning and release-note commits
Canonical docs gate includes entry docs, runbooks/checklists, decision matrix, migration map, expected outputs, and performance characterization pages

Required release checkpoint:

Release PR is not ready until docs integrity passes and the release-note-to-docs delta checklist is complete.

For each release PR, reviewers must confirm:

CHANGELOG.md entries are reflected in affected user docs
New/changed API surface has corresponding wiki or README guidance
Added/renamed examples are reflected in ta4j-examples/README.md and relevant wiki links
Removed/deprecated APIs are called out with migration direction
Any changed execution semantics are reflected in backtesting/live docs

Run a rubric refresh before each minor/patch release
Re-run docs integrity checks in every release-prep workflow
Track recurring user confusion patterns and resolve them in docs, not only in chat/issues

Freshness SLA for primary user docs (README, ta4j-examples/README, Home, Getting-started, Backtesting, Live-trading):

Change-window SLA: update docs within the same PR when behavior/API changes.
Release SLA: no unresolved TODO markers or broken references at release prepare time.
Navigation SLA: new high-value pages must be linked from Home or _Sidebar before merge.

Dimension-to-evidence review checklist (required before scoring >=4.5):

Coverage evidence: canonical path includes build, backtest, live, and incident handling references
Clarity evidence: entry pages define exact next-step routing for primary user intents
Operability evidence: checklist/runbook includes validation signals and escalation flow
Discoverability evidence: canonical artifacts are visible in both entry copy and nav menus
Freshness evidence: integrity checks and release checklist cover all canonical docs
Canonical artifact set exists and passes integrity checks before release preparation

This snapshot records overlap metrics before the “documentation surface-area consolidation” rollout.

Execution-choice guidance appears in multiple entry pages (Home, Getting-started, Backtesting) instead of one canonical decision surface.
Onboarding and “where to go next” guidance is duplicated across root/module READMEs plus wiki entry pages.
Wiki-link style is inconsistent in repo docs:
- .github/CONTRIBUTING.md currently points to github.com/ta4j/ta4j-wiki/wiki/...
- Other docs mostly point to ta4j.github.io/ta4j-wiki/...
Runtime baseline wording is inconsistent:
- Root docs and contributing docs state Java/JDK 25+
- ta4j-examples/README.md states JDK 21+

Sidebar duplicate targets: 6 -> <=1
Root README.md wiki link repetition (total vs unique gap): reduce by at least 40%
Execution-choice decision tables: consolidate to a single canonical page
Broken links after each phase: 0