Create document on how to work with OSCAL JSON and XML

[akarmel]

User Story

As an OSCAL Consumer, I have documentation that explains how to use OSCAL from both a JSON and XML perspective.

Goals

• Develop OSCAL documentation that explains how to make use of OSCAL from both a JSON and XML perspective
• Make prominent use of JSON and XML Schemas and promote the use of RelaxNG due to poor commonly available support
• Present how to make use of the OSCAL XML Schema and schematron

Dependencies

• Automated Alignment between OSCAL JSON and XML need to be completed per issue Automated OSCAL specification translations and mappings from XML schema to JSON schema #125

Acceptance Criteria

• Verify that documentation exists, is concise, accurate and sufficiently explanatory (e.g. clearly explains how to use OSCAL from both a JSON and XML perspective) for an user that has no previous deep knowledge/understanding of OSCAL.

[iMichaela]

** 3/14/2018 **
Updated the Acceptance criteria.

[akarmel]

3/15/2018 - Sprint 9 Progress Notes

• The team will be working on this once Refactor the catalog and profile schema to remove unused elements #124 and Automated OSCAL specification translations and mappings from XML schema to JSON schema #125 is complete

[kscarf1]

Yesterday I revised the catalog XML schema documentation to reflect the latest schema. File is at https://github.com/wendellpiez/OSCAL/blob/docs/source/includes/schema/_catalogXML.md.

[kscarf1]

I created basic profile XML schema documentation based on the latest schema and the documentation it already contains. File is at https://github.com/wendellpiez/OSCAL/blob/docs/source/includes/schema/_profileXML.md

[akarmel]

3/22/2018 - Sprint 9 Progress Notes

• See Karen's comments above
• Karen wil continue to work on narrative material next week
  • NOTE: This issue may be affected by 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. I will be completing the documentation for OSCAL consumers in preparation for deployment to pages.nist.gov. The documentation will be ready in draft format by Wednesday, April 4th for review and discussion during the Thursday weekly call. This will give us time to finalize the documentation before publication to pages.nist.gov.

[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

[kscarf1]

I have finished updating the catalog and profile XML schema documentation (https://github.com/wendellpiez/OSCAL/tree/docs/source/includes/schema) to use the latest XML schema versions. I'm currently awaiting word on whether the JSON schema files are ready to be documented or if that should be delayed to another sprint.

[kscarf1]

I have completed the documentation for the JSON catalog and profile schemas. All documentation needed for this issue has been completed and is pending core team review.

[akarmel]

4/5/2018 - Sprint 9 Progress Notes

• See Karen's progress note above
• Meeting scheduled for next Monday to review documentation

[akarmel]

4/12/2018 - Sprint 9 Acceptance

• Complete
• Closing issue