ASHRAE 232 §6.1 requires five documentation elements for a conformant data model specification: Identification (6.1.1), Version History (6.1.2), Use Case (6.1.3), and Scope and Description — Applicability (6.1.4.1) and Exclusions (6.1.4.2) — alongside the Data Model, Verification Rules, Publishing Rules, and Application Rules sections that downstream .md.j2 templates already tend to include by convention.
Lattice doesn't generate or document a recommended skeleton for that doc-content template — each project hand-authors its own headings. In practice, Identification, Version History, and Use Case have been getting dropped: IBPSA-USA/output-reporting's docs/OutputReporting.md.j2 only had Scope/Data Model/Verification/Publishing/Application Rules until this was caught and fixed by hand, and climate-information's ClimateInformation.md.j2 still doesn't have them.
Proposed: provide a documented or generated skeleton (wherever a new lattice-based data-model project's doc template gets scaffolded) that stubs all five §6.1 elements, not just the four most projects happened to start with.
Related to #12 — once schema meta (schema_name, Schema: Version) can be pulled into web docs automatically, Identification and Version History could partly auto-populate instead of being hand-written prose in every downstream project.
ASHRAE 232 §6.1 requires five documentation elements for a conformant data model specification: Identification (6.1.1), Version History (6.1.2), Use Case (6.1.3), and Scope and Description — Applicability (6.1.4.1) and Exclusions (6.1.4.2) — alongside the Data Model, Verification Rules, Publishing Rules, and Application Rules sections that downstream
.md.j2templates already tend to include by convention.Lattice doesn't generate or document a recommended skeleton for that doc-content template — each project hand-authors its own headings. In practice, Identification, Version History, and Use Case have been getting dropped:
IBPSA-USA/output-reporting'sdocs/OutputReporting.md.j2only had Scope/Data Model/Verification/Publishing/Application Rules until this was caught and fixed by hand, andclimate-information'sClimateInformation.md.j2still doesn't have them.Proposed: provide a documented or generated skeleton (wherever a new lattice-based data-model project's doc template gets scaffolded) that stubs all five §6.1 elements, not just the four most projects happened to start with.
Related to #12 — once schema meta (
schema_name,Schema: Version) can be pulled into web docs automatically, Identification and Version History could partly auto-populate instead of being hand-written prose in every downstream project.