Type
Task
Scope
Multi-theme or Platform
Skillset
engineering
Description
The repository's Python documentation is unreachable and conflates several audiences.
Unreachable. PYDANTIC_GUIDE.md and README.pydantic.md are referenced by no file in the repository, and README.md does not mention the Python packages at all. A contributor has no path to either document except by browsing the file listing.
Conflated audiences. README.pydantic.md interleaves project rationale (why Pydantic rather than JSON Schema), consumer instructions (install, validate data), and contributor setup. No part of it can be revised independently of the others, which is part of why it drifts.
Unverified. Both documents accumulated errors that were never executed. #604 and #668 catalogue the ones found so far; #683 fixes them and adds a check for the class. That check does not address structure, and structure is what makes the documents hard to keep correct: a reader who cannot find a document cannot report that it is wrong.
Suggested approach
Consolidate into a single guide, linked from README.md and CONTRIBUTING.md, with the audiences separated at the top level rather than interleaved — rationale, using the schema, extending and authoring it, reference. Expand GLOSSARY.md to cover both the data model (theme, type, subtype, GERS) and the Python toolchain (entry point, workspace, discriminated union), since the two vocabularies are currently mixed in prose without definition.
Acceptance
Notes
Dana Bauer (@danabauer) opened #672 doing this work; it predates the fixes in #683 and so carries the stale content forward. #684 is that work rebased onto #683 with the corrections applied.
Type
Task
Scope
Multi-theme or Platform
Skillset
engineering
Description
The repository's Python documentation is unreachable and conflates several audiences.
Unreachable.
PYDANTIC_GUIDE.mdandREADME.pydantic.mdare referenced by no file in the repository, andREADME.mddoes not mention the Python packages at all. A contributor has no path to either document except by browsing the file listing.Conflated audiences.
README.pydantic.mdinterleaves project rationale (why Pydantic rather than JSON Schema), consumer instructions (install, validate data), and contributor setup. No part of it can be revised independently of the others, which is part of why it drifts.Unverified. Both documents accumulated errors that were never executed. #604 and #668 catalogue the ones found so far; #683 fixes them and adds a check for the class. That check does not address structure, and structure is what makes the documents hard to keep correct: a reader who cannot find a document cannot report that it is wrong.
Suggested approach
Consolidate into a single guide, linked from
README.mdandCONTRIBUTING.md, with the audiences separated at the top level rather than interleaved — rationale, using the schema, extending and authoring it, reference. ExpandGLOSSARY.mdto cover both the data model (theme, type, subtype, GERS) and the Python toolchain (entry point, workspace, discriminated union), since the two vocabularies are currently mixed in prose without definition.Acceptance
README.mdorCONTRIBUTING.md.Notes
Dana Bauer (@danabauer) opened #672 doing this work; it predates the fixes in #683 and so carries the stale content forward. #684 is that work rebased onto #683 with the corrections applied.