NIST Team: Personal Recommendations on Tutorials Roadmap #1871
Replies: 8 comments 1 reply
-
I see both advantages and disadvantages with an integrated approach. On balance however I see nothing wrong with starting this way. However if/when people have ideas that diverge, I hope they are not blocked for that single reason - any workable strategy must be adaptable. (We don't want to discourage anyone at all from making any kind of OSCAL tutorial as long as the information is good.)
I think that's a great idea. I also think that the same "simplified lifecycle" might be iterated with variations, later or even sooner. (For example: same task, different tools.)
This is difficult. We need to be dynamic, responsive and creative. This should mean frequent updates and maybe dramatic changes (so not to be skittish about that). I don't even think we have a clear idea of what it means to "use" OSCAL. The workshop curriculum so far is better than our online tutorials in this respect. Also, I think we have a problem due to inconsistent knowledge of the rudiments, e.g. what is schema validation (or harder, what it is not). We need to think about teaching here by demonstration, since many users don't perceive their own ignorance.
Issues I see with the current tutorials are not with their scope so much as with the perspectives they assume. For example, almost no one would be tagging metadata by hand, as seems to be assumed in the Metadata tutorial. It should be amended/rewritten from another point of view, maybe for a developer who is surveying the model to build a UI, or the user of such a UI (even if it's a fictional mockup). (For that matter why aren't we providing a workable front end for form-filled OSCAL Metadata production, instead of a tutorial guide for tagging a la 1995?)
I think we have two choices: (a) remove everything and put back what we want, or (b) survey it all (as a group/team). Since we are not aligned on plans/purposes yet, choice (a) might be easier for now. Then we take up the issue of data governance on this site. (I assume we are talking about non-FISMA content as noted.)
It's a big job and breaking it into pieces / lanes will help, as will empowering team to introduce and execute on make improvements. I have an old war story about this, if you like. |
Beta Was this translation helpful? Give feedback.
-
I like the idea (I promoted it) of creating small stand-alone examples that are then integrated into a broader picture. For example, the Catalog tutorial used very simple ISO control to demonstrate OSCAL versatility, and to have controls very simple to format. Profile and profile resolution tutorial needed more complex controls to demonstrate the functionality. We can show a derived profile form both to demonstrate such functionality. We can also include the control(s) implemented in the Component Definition example, so, when working on a CDef Tutorial we reuse the example and have the 'sourced' profile ready. Each of those steps demonstrate features and can be used as stand alone but also provide some continuity.
Starting simple with fewer actors makes explanations easier.
Keep and enhance with new ones
All examples need to be updated to OSCAL 1.1.0!
|
Beta Was this translation helpful? Give feedback.
-
Yes, integrated examples will help beginners to understand the tutorials.
Agree.
Presuming this means "How To OSCAL" tutorials, I would recommend this.
I'll have to expand on my answer. (I'll update or reply to this comment at a later time.)
We should survey what we already have and build from there. First update existing content and then add/amend to fill any gaps.
None. |
Beta Was this translation helpful? Give feedback.
-
I agree with both. I'm assuming actor-based scenarios are based on perspectives of roles similar to the workshop presentation and I think this is great for helping others understand the points where OSCAL fits in the overall workflow.
To build on the success above, based on my experience in systems and applications architecture, most conversations occurred around network diagrams and I think it would help here. I believe everyone would benefit from a few reference architectures that present common scenarios, and then we can demonstrate how the models are used to document the system. I personally feel a bit lost with OSCAL when mentally putting together a system using the constructs we've provided. For example, the use of components seems very straight-forward to most in the community from the security perspective, but I have issues applying the concepts based on my experience developing and deploying systems. I'd chalk that up to my own brain having issues, but I know enough to know something is not quite right. I'll also share, as a personal experience, that RMF wasn't applied until we knew what we planned to build, and often it was already in development. So when controls were selected, we generally understood what was needed, and it was much easier to reason through. Without diagrams, it's hard to conceptualize specifically how a system is "componentized" or modeled, and selection of controls feels premature.
Keep building tutorials, but with the context above. Let's model systems.
I'd rather see examples as snippets integrated into the metaschema documentation. I think I'm used to reading through API documentation, and that's what I'm missing. The end result code for the tutorials could be in oscal-content. One loss from having just the single repo would be the ability to step through using branches like we did with the case study. That seems hard to maintain on a more broad scale though. Another option would be the case study style approach where each reference system is a repo. (Just brainstorming)
Ultimately I think we seek to avoid writing OSCAL by hand, and encouraging others to do the same, particularly if our scenarios are centered around the composition of OSCAL. How do we support the tools creators to build the best tools so that, generally, OSCAL is in the background doing its job? I feel like building up OSCAL-Reference so that it is very similar to other API references will help developers. Having the reference architectures will likely help them too. On documentation, I've said it before, but one of my favorite API sites is https://pandas.pydata.org/docs/ Others: |
Beta Was this translation helpful? Give feedback.
-
|
I love the idea of integrating examples into the model documentation pipeline directly. We could probably repurpose the remarks section of the metaschema, or propose separate |
Beta Was this translation helpful? Give feedback.
-
|
I do not understand what happened to my earlier responses... after Wendells. They were even endorsed.. (+1). I refreshed the page and they re gone! I'll try to reproduce. |
Beta Was this translation helpful? Give feedback.
-
|
SO ... Maybe I did not hit send comment earlier :( ... Here it is again.
YES! I have been promoting the design of tutorials that provide a coherent , progressive approach from the beginning. When I created the Catalog tutorials we needed very simple controls so I selected ISO/IEC 27002 controls to also demonstrate OSCAL's versatility. A second Catalog tutorial was bringing more complex controls, but was not published. Profile tutorial demonstrated more complex controls from 800-53 so it can demonstrate also how to resolve profiles. I am hot tutorials that can be studies as independent material but which belong to a larger, comprehensive picture.
YES! Start simple so it is easy to follow.
Here is what I would do:
Keep, add new ones, update them to OSCAL 1.1.0. Save the OSCAL content to examples. The Catalog has the example saved, the Profile does not.
Update them to OSCAL 1.1.0, reuse them as described above. Add more examples.
During our first OSCAL workshop, during the hackathon, people were trying to create fillable forms for SSP. I thought is would be a cool idea but maintain such editorial tool(s) could turn into a nightmare for us. |
Beta Was this translation helpful? Give feedback.
-
|
Submitting this a bit later as I was out on AL.
I agree that we should move towards a set of "integrated" tutorials, however I do not think it should be a hard rule.
Role-centric tutorials should help users get a clearer understanding not only of what OSCAL is, but how they and their team will interact with the models.
I think that a new set of tutorials will need to account for two different "modes":
With both of these types of tutorials in mind, it may make sense to create a "tutorial landing page" that offers curriculums (or tutorial playlists) centered around different roles and use-cases.
It may make sense to keep the existing tutorials as they still serve as good introductions to the profile and catalog models and are pretty self-contained.
I'm not sure that the examples are useful outside of the context of the tutorials they are built out of.
However we approach tutorials we should ensure that we are not creating a maintenance burden. |
Beta Was this translation helpful? Give feedback.
-
|
@aj-stein-nist @nikitawootten-nist the Metaschema model already has support for inline examples. 😎 However, for the sake of Metaschema maintenance these need to be kept lightweight -- and it would also support linking to examples out of line, which could be transcluded (sucked in) in the documentation display, or linked to. At one point -- briefly, a long long time ago -- the OSCAL Metaschema XSD had a hook enabling you to connect another XSD to it, to validate example content. But since examples are not typically rooted at the root, this is not always useful. But |
Beta Was this translation helpful? Give feedback.
-
Hello, fellow NISTer working on OSCAL. We are going to use this discussion board to collect team member perspectives on changes big and small to how we publish tutorials. I think there is room for improvement (isn't there always?), and I think it is good to also let the community understand our perspectives and final plan after the fact by reading this, so we will post it here. I hope to have feedback for consideration by close of business 5:00 PM ET on 7 August 2023. I likely will not be able to consider any staff feedback after that time if posted here.
By now in the sprint, you probably should have read usnistgov/OSCAL#1867. That issue will end up in a plan, not the work itself, but there are still some dependencies for that roadmap and this preparation (reading current tutorials, review example oscal-content that isn't the 800-53 catalog, and 4th conference workshop materials to understand my opinionated perspective on this). If you have not done that pre-work, read those first and come back to this.
So, re desired feedback, if you have any feedback, I would strongly encourage you to address the list of recommended steps in the current issue like below. Again, feedback should be submitted by close of business 5:00 PM ET on 7 August 2023. Thanks again!
Your answer here.
Your answer here.
Your answer here.
Your answer here.
Your answer here.
Your answer here.
Beta Was this translation helpful? Give feedback.
All reactions