Determine a way to auto-document the catalog and profile models

[wendellpiez]

User Story:

As an OSCAL user, I can find current and complete documentation of elements and attributes permitted in OSCAL.

• Allow auto-generation of in-schema docs
• Allow auto-generation of website schema documentation
  • Present a tree-form rendering of the model with links to the specific element definitions
  • Link to the actual schema (on the github site)
• Develop code examples for each element in XML and JSON

Goals:

• Update and continue to extend schema documentation infrastructure.
• Like earlier schema documentation, this can be injected into XSDs as well as exposed for external consumption

Dependencies:

Models (especially regarding profiling) and element semantics are considered stable enough to document, all dependent on #124

Acceptance Criteria

• Schema documentation has been extended to describe new elements
• Attributes are also described including global attributes such as @class

[wendellpiez]

Progress report Mar 22 - the new element descriptions have been added to schema docs - also, docs processing now emits auto-generated link lists btw elements, as well as document all attributes - more remains to be done - plus integration w/ official documentation backend cf #15 #129 #130

[akarmel]

3/22/2018 - Sprint 9 Progress Notes

• See Wendell's note above
• Per Wendell, this is 80% complete
• Wendell and Karen need to connect on this topic. Will weave this into the documentation workflow conversation scheduled next week per issue Document the composition of the profile schema and how it relates to the catalog schema #130

[kscarf1]

Wendell, Dave, Andrew, and I met to discuss documentation workflow. We have high-level agreement on an approach to take, but our immediate priority is to have documentation ready before the RSA Conference. The group agreed that we should finish manually creating the initial documentation for RSA on catalogs and profiles, and then return to this issue once that documentation is ready. We will be able to migrate the manually created content into the oscal-oscal.xml files and others for future use in documentation auto-generation.

[akarmel]

3/29/2018 - Sprint 9 Progress Notes

• See Karen's progress note above
• Will review the documentation during next Thursday's status meeting
• DECISION: OSCAL Consumers and Producers will be treated the same as opposed to as separate audiences...will develop one uniform set of documentation
• DECISION: Documentation will be produced outside the standard OSCAL Documentation Workflow pipeline as the pipeline is still in development
• See Dave's proposed OSCAL development pipeline model below
  • Next sprint can focus on preliminary design of the implementation model with the rest of the time spent working on this pipeline model and the automation of the same (possibly with Travis - public CI service)

[akarmel]

[wendellpiez]

Latest:

• https://github.com/wendellpiez/OSCAL/blob/sprint-9/docs/schema/_catalogXML.md
  • compare to https://github.com/wendellpiez/OSCAL/blob/docs/source/includes/schema/_catalogXML.md
• https://github.com/wendellpiez/OSCAL/blob/sprint-9/docs/schema/_profileXML.md
  • compare to https://github.com/wendellpiez/OSCAL/blob/docs/source/includes/schema/_profileXML.md
• bonus track! https://github.com/wendellpiez/OSCAL/blob/sprint-9/docs/schema/_profileXML.md

These documents are driven out of oscal-oscal.xml and "through" their respective schemas to pick up structured descriptions of contents, etc.

Eventually (or maybe soon?) this can be turned upside down, with the schemas generated instead of maintained separately.

[akarmel]

4/5/2018 - Sprint 9 Progress Notes

• See Wendell's comment above
• Karen is pleased with the documents that have been autogenerated
• Meeting scheduled for next Monday to review both auto-generated and manual documentation as well as develop a plan to stitch all this together moving forward

[akarmel]

4/12/2018 - Sprint 9 Acceptance

• Complete - need a separate user story for code examples.
• Closing issue