Roadmap for OSCAL Tutorials

[aj-stein-nist]

User Story

As an OSCAL community member developing OSCAL-based software, I want to understand how to use OSCAL data formats for a simple information security lifecycle in context: who are notional actors, what do they do (in the form of relatable use cases), how do they represent OSCAL data, and when do these things in a lifecycle. I would like the examples on the updated website, and I want the example data in usnistgov/oscal-content to match up with it.

Goals

• Team to draft a roadmap that specifies:
  • An approach to integrated examples that are logically connected to the tutorials, not isolated
  • A simplified lifecycle based around actor-based scenario and use cases
  • An updated list of tutorials demonstrating their usage
  • A list of recommendations after reviewing existing tutorials to recommend: keep, amend, or archive
  • A list of recommendations on examples in oscal-content/examples to: keep, amend, or archive
  • A list which identifies the examples embedded into keep or amend tutorials that are not provided as stand alone examples in oscal-content/examples.

Dependencies

• Team to review all existing tutorials.
• Team to review the 4th OSCAL Conference workshop
• Review of oscal-content examples

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

(For reviewers: The wiki has guidance on code review and overall issue review for completeness.)

Revisions

I have updated and scoped down the list of acceptance criteria. Given the roadmap thus far, it seems odd to predetermine the list of tutorials and examples that need to be removed or signficantly refactored before the "inventory of OSCAL use cases" are done.

[aj-stein-nist]

@usnistgov/itl-oscal I expect anyone in the team who has opinions on the roadmap before the beginning of next week to draft a proposal here for follow-on discussion and review next week.

#1871

[aj-stein-nist]

I drafted a provisional roadmap for discussion with the team during review:

https://hackmd.io/8ObwcnJkQzeTZfHCro6tPA?view

[iMichaela]

I drafted a provisional roadmap for discussion with the team during review:

https://hackmd.io/8ObwcnJkQzeTZfHCro6tPA?view

@aj-stein-nist -- The HackMD file is locked for editing. Left some comments, but providing edits would be more efficient.

Concern: The proposed roadmap is not taking in consideration the existing tutorials and provides no proposal on how to integrate (and expand) the examples used in those tutorials, in a way that is avoiding trashing them in favor of a completely new set. Please unlock the file or advise where to capture ideas that would reuse current examples or integrate them onto the redesigned suite.

[aj-stein-nist]

Thanks for reading it @iMichaela. The roadmap is supposed to be high-level. The implicit proposal, and I can clarify that if you'd like: we lay out the goals we want to demonstrate certain use cases. If an existing tutorial or example can be adapted, it will be. If cannot fit into the roadmap with significant adaptation, it can be removed and/or archived elsewhere. I hope that clears things up.

[iMichaela]

If an existing tutorial or example can be adapted, it will be.

Great. Thank you, @aj-stein-nist

If cannot fit into the roadmap with significant adaptation, it can be removed and/or archived elsewhere.

I see no reason to archive as obsolete current/updated examples that do not fit into the 'flowing' tutorial suite. They still bring value to our community. If their maintenance is an issue for us, maybe we can donate/recycle them to the community and move them to Awesome OSCAL, OSCAL.io, or even to EUROSCAL.eu