Document the composition of the profile schema and how it relates to the catalog schema

[kscarf1]

User story candidate: As a content or tool developer, I can find clear, concise, and accurate information on the composition of OSCAL’s catalog and profile schemas and how they relate to each other.

Required Resources:

• Stable OSCAL catalog schema
• Stable OSCAL profile schema
• Feedback on original OSCAL catalog schema documentation

Goals:

1. Produce a profile schema with embedded documentation (usable by tools).
2. Make documentation of the profile schema tag set accessible in the GitHub repository.
3. Make the profile schema tag set documentation available in multiple formats, to include HTML and Markdown, that can import cleanly into Word, Powerpoint, and/or other appropriate production platforms.
4. Document the high-level conceptual description and description "tags" (elements) for the profile schema in OSCAL.
5. Make any needed revisions to the catalog schema, catalog schema tag set documentation, and documentation of the high-level conceptual description and description tags for the catalog schema.

Acceptance Criteria:

1. Validate that profile schema documentation can be made available when working with OSCAL in oXygen.
2. Validate that documentation on the profile schema tag set is online and available in GitHub.
3. Validate that the same catalog and profile documentation appears in HTML and Markdown formats.
4. Verify that the contents of the catalog and profile schema documents make sense.
5. Verify that all catalog and profile schema element descriptions are accurate and concise.
6. Be ready to share the catalog and profile schema documentation for review by interested parties (tiger team, Fred, Jaafar).

Was originally issue #15

[kscarf1]

Old status notes from issue #15:

2017-12-05: Sprint 6 Progress Notes from akarmel. kscarf1 needs to be added to this GitHub repo so she can see the issues assigned to her. Michaela is adding her to this GitHub repo and Anil will add her to the issues assigned to her.

2017-12-12: Sprint 6 Progress Notes from kscarf1. I am going to focus on issue #58 first to come up with a cohesive approach for structuring and organizing all OSCAL documentation. After we have consensus on that approach, then I can employ the approach when I work on this issue.

2018-01-09 from kscarf1: We are still focusing on issue #58 at this time, and we will be taking a different approach to documenting the catalog and profile schemas than was originally expected. I'm currently working on a strawman for how we would document a control, which is needed as part of the catalog and profile documentation. Once the strawman is solid and issue #58 is completed, we can move forward with addressing this issue.

2018-01-11 from akarmel: Sprint 6 Acceptance. This is on hold until issue #58 is addressed (see above comment)

2018-03-08 from akarmel: Adding issue #93 to this issue

2018-03-15 from akarmel: 3/15/2018 - Sprint 9 Progress Notes. Karen hasn't started working on this yet in this Sprint. Working on bringing documentation over to the Slate framework.

[kscarf1]

I have updated the catalog XML schema documentation file to reflect the latest catalog schema. I have created a profile XML schema documentation file and renamed the old profile schema placeholder file to be a placeholder for profile JSON schema documentation. All these files are located at https://github.com/wendellpiez/OSCAL/tree/docs/source/includes/schema.

[akarmel]

3/22/2018 - Sprint 9 Progress Notes

• See Karen's comment above.
• Need to coordinate efforts between Wendell, Karen, David, Andrew and Michaela to discuss the documentation workflow - Karen will coordinate the call

[kscarf1]

Wendell, Dave, Andrew, and I met to discuss documentation workflow. I will be completing the documentation on the profile schema for OSCAL consumers and producers 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 expanded the documentation (https://github.com/wendellpiez/OSCAL/blob/docs/source/concepts/index.html.md) to include profiles and explain how profiles and catalogs relate. I have also revised the profile XML schema documentation to use the latest schema version (https://github.com/wendellpiez/OSCAL/blob/docs/source/includes/schema/_profileXML.md). I am checking on whether the JSON profile schema is ready to be documented.

[kscarf1]

I have completed initial documentation of the JSON profile schema. All documentation needed for this issue has been drafted and is ready for the core team to review.

[akarmel]

4/5/2018 - Sprint 9 Progress Notes

• See Karen's updates above
• Documentation has been created and run through Slate, it's now ready for review
  • Dave will schedule a meeting next week with Wendell, Karen and Andrew to discuss this issue (will use Karen's WebEx)
    • Will also use this time to discuss the plan to publish pages.nist.gov/OSCAL

[akarmel]

4/12/2018 - Sprint 9 Acceptance

• Complete.
• Closing issue.