Update OSCAL Catalog and Profile schema documentation

[akarmel]

User Story:

As an OSCAL content consumer, I have clear, concise and descriptive documentation describing the Catalog and Profile layers of OSCAL.

Goals:

1. Develop clear, concise and descriptive documentation describing the OSCAL Catalog with input from the OSCAL Team (@PCrayton with review from @david-waltermire-nist @wendellpiez )
2. Develop clear, concise and descriptive documentation describing the OSCAL Profile with input from the OSCAL Team (@PCrayton with review from @david-waltermire-nist @wendellpiez )
3. Develop XML (e.g., element, attribute) and JSON (e.g, arrays, maps, objects, names/labels, members/values) specific terminology (@david-waltermire-nist @wendellpiez)
4. Technical Edit OSCAL Catalog and Profile documentation (@bbattaglini)
5. Develop more comprehensive descriptions of the OSCAL model and each data structure, the semantics, content requirements and valid values (@bbattaglini)

Dependencies:

None

Acceptance Criteria

1. OSCAL Catalog and Profile documentation exists, has been technically edited and reviewed by the OSCAL Team
2. OSCAL Catalog and Profile documentation has been published in the OSCAL GitHub repository

[kscarf1]

June 27, 2018 status: Standing by to help when needed.

[iMichaela]

6/28/2018 Status

Reviewed the user story to reflect the scenario discussed during the meeting.

[wendellpiez]

Many edits and improvements have been made in documentation in PR #201, but much remains to be done. In particular, while a better production framework is now in place for schema documentation, our editorial workflow is not; until it is, further work on this Issue is hindered.

Since schema documents start with their metaschemas, editorial workflow for the documentation is tied to metaschema maintenance. However, an early goal could be to stabilize the catalog and profile metaschemas as soon as possible ("finishing" their inline documentation), permitting us to move the focus of effort to other useful kinds of docs (guides, tutorials etc). At time of writing, only the embedded docs are in place (started) but not finished.

[iMichaela]

July 18 Status Update (Sprint 12 Acceptance Meeting)

The issue was not assigned to any member of the team in Sprint 12 and we will push the issue to Sprint 13

[PCrayton]

8/9/18 Status

1. Created a rough draft of the catalog documentation. 40% Complete
2. Created outline of the profile documentation. 20% Complete
   Issues: None at this time.

[PCrayton]

8/23/18 Status
Worked today with @wendellpiez on the documentation of catalog elements. Will incorporate Wendell's input into the catalog draft and forward it to @david-waltermire-nist for his review
Issues: None at this time.

[PCrayton]

8/30/18 Status
Working on incorporating input from @wendellpiez and properly documenting the usage of parameters as per Issue #190
Issues: None at this time

[PCrayton]

9/6/18 Status

Shared documentation efforts with @david-waltermire-nist and received his input. Will incorporate it and work with @wendellpiez to set up a proper Github pipeline for production.

[PCrayton]

9/13/18 Status

Worked with @wendellpiez to set up a Github pipeline for production of documentation. Working on incorporating input from @david-waltermire-nist and @wendellpiez on the catalog and profile schemas.

[iMichaela]

9/26/2018

@PCrayton received feedback from @wendellpiez and need just a little more time (low effort) in Sprint 14.

[iMichaela]

10/4/2018

This issue is related to #190 . @PCrayton Peter can wrap it by the end of next week. @david-waltermire-nist will review tomorrow the drafts.

[david-waltermire]

10/11/18 Status

---

@PCrayton Will open a PR with the completed catalog and profile documentation in their respective metamodels. @wendellpiez and @david-waltermire-nist will review this.

[iMichaela]

11/08/2018

@david-waltermire-nist is reviewing the PR

[david-waltermire]

11/15/2018

@david-waltermire-nist will accept PR #255 and we will plan new documentation activities to further improve the documentation in sprint 16.

[david-waltermire]

Need to review schema docs and make sure they are clear enough. Might be able to use some docs from PR #255. Make updates as needed.

[iMichaela]

5/23/2019

Needs update from @david-waltermire-nist . The issue will require coordination.

[david-waltermire]

This work is happening in #387.