Docs: make the PROV-O export discoverable from every newcomer entry point - #14
Merged
Conversation
…oint An audit of how a newcomer would find the feature showed depth without discovery: PROV-O lived only in a ticked roadmap bullet (reads as history), the prior-art list, and a stale status line still calling it 'next'. Now: a components-table row (the page's actual feature index), a glossary entry in the fact-contract group, an FAQ answer for the question a governance team actually asks, and the status line updated to 'M4 underway — PROV-O shipped'. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Answers the review question "is the PROV-O work sufficiently documented for someone new?" — the audit said depth yes, discovery no. The spec, mapping tables, SPARQL demo, and endpoint all exist, but every path a newcomer actually walks failed to lead there: the feature lived only in a ticked roadmap bullet (which reads as history, not "this exists — use it"), the prior-art list, and a status line still calling PROV-O "next" after it shipped.
Four small fixes:
PROV-O exportrow in the page's actual feature index, linking the spec, the runnable SPARQL demo, and the?format=jsonldendpointdocs/concepts.md— a glossary entry in the fact-contract group: what expands to what, the lineage question it answers, and the deliberately-partial boundarydocs/faq.md— the question a governance team actually asks ("can our existing lineage tooling read duly's audit trail?"), answered with both consumption paths and the honest boundaryMerge-order note: the glossary/FAQ links to
spec/provo_sparql_demo.pyresolve once #13 merges — merge #13 first (or together; nothing conflicts).🤖 Generated with Claude Code