User Story:

Consistency and usage of language and terminology in documentation including editorial policy can to a certain degree be supported with Schematron. For example, a Schematron rule can say 'descriptions should not be full sentences, only phrases' and then detect periods or other forbidden punctuation. More generally (and more lightweight), queries such as //formal-name will help us take a top-down view of the usage of this element.

Goals:

Develop and apply some simple queries to run over Metaschema source, to provide editorial support and improve the level of 'polish' of the design and resulting documents. Deploy them as either/both Schematron or (documented) XPath/XQuery.

Making the actual changes is not in scope for this Issue; it can either be done as part of regular editorial work, or spun into an Issue of its own. However, this Issue can be considered done as soon as we have some means of assurance that the docs have the needed consistency, with long-term support tooling being a spin-off goal.

Example rules (for discussion / tbd):

• formal names should be in title case (capitalized)
• list items should be constituted of phrasing, not sentences
• list items punctuated with ; (?)
• same with allowed-values/enum
• same with descriptions
• descriptions should not include parentheses/brackets? etc.

Dependencies:

None.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}