Define how a milestone checks that the documents read correctly

Open
  • Is something wrong?
#132 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Domain
documentation

Research direction

Read the existing gate and milestone reports under docs/_integration/*/report.md, and find where "reads correctly" appears in docs/_integration/README.md. Check the figures against coverage-matrix.json, generator-ready.json and doc-source.json. Done when the README has a reading procedure covering documents, views, a sampled per-entity checklist and how findings are recorded, and the last section of the report carries that checklist. The re-check grep in the issue should then find the procedure.

Written by the indexing model from the issue text.

Description

type:tech-debt
Description of Technical Debt

Every gate and milestone report under docs/_integration/ ends with a "reads correctly" verdict. No page says what is
read, against which source, or how the reading is recorded. The reports so far restated the automated checks, compared
generator-ready.json with doc-source.json field by field, or held one sentence per document. The verdict is the
owner's yes or no.

Impact of Technical Debt
  • The verdict cannot be repeated by someone else.
  • A defect a reader would see, such as wrong grouping, a missing badge or a coverage figure that does not match, passes when the automated checks are green.
Category

Testing / Test Coverage

Priority

Low - Nice to have

Proposed Solution

In docs/_integration/README.md, a reading procedure: which documents and views, a fixed checklist against the source (per entity type, sampled: title, state badge, criteria and aspects, coverage figures against coverage-matrix.json), and how a finding is recorded. The report's last section carries that checklist.

Effort Estimate

1 day

Dependencies / Related

The tutorial-capture epic will need the same for rendered tutorials.

Additional Context

Measured 2026-11-12 at living-doc 2df73dc. Re-check:

grep -n "reads correctly" docs/_integration/README.md docs/_integration/*/report.md

Dominant language
Python
Stars
0
Forks
0
Avg merge
6h 14m
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.