Request for Comment: Recommendations for Separation of High-Level and Technical Documentation

[ohsh6o]

User Story:

As OSCAL users of varied background and experience, in order to best educate and evangelize OSCAL to new community members, I would like high-level documentation and technical data model documentation to more clearly split to not overwhelm users and more carefully control proper and meaningful versioning of the technical documentation (whereas it is less applicable to high-level docs conceptual docs applicable to all versions).

Goals:

Per last week's developer meeting, @david-waltermire-nist had requested an issue be created as a request for comment from the OSCAL community regarding changes to the split between the high-level conceptual docs and technical documentation. For the documentation, user feedback was requested regarding:

• Do community members support separation of high-level conceptual and technical data model documentation?
• Do community members support explicitly versioning the technical docs and allow explicit historical and ongoing access to technical docs for published OSCAL versions?
• If so, does the community have specific recommendations on how versioned technical docs are presented?
• For high-level conceptual docs, does the community have any recommendations regarding how to structure high-level conceptual documentation?
• Are the current personas and scenarios sufficient and need further detail?
• Should different persons be added?
• Should the high-level conceptual documentation be organized in some other way not driven by these personas?

Dave and the NIST OSCAL dev team asked that feedback be provided as comments in issues such as this to make it easier to track feedback and accepted recommendations.

[aj-stein-nist]

Will discuss with @david-waltermire-nist and recommend closing as 1) this story did not get a lot of feedback at the time 2) might now be obsolete. IIRC, it stemmed from a discussion that happened prior to splitting conceptual documentation and technical reference docs version by version for OSCAL. That seems to be correct by git spelunking at 85e7d01.

Will discuss with Dave and team whether or not, given no external feedback post issue creation, if there is more work to be done here.

[aj-stein-nist]

It would seem given the previous comment and [the split-out of the content site and reference doc site with the repo re-org), it seems this has already been done. Since I opened the issue in a prior role, I will mark this one closed.