Doc cleanup for issue usnistgov#138 (usnistgov#157)

Doc and README cleanup for issue usnistgov#138
* Removed presentation files.
* Removed unneeded Markdown files
* Began cleanup of README.md files.
* Moved paragraph within the root README.md

README.md

@@ -1,15 +1,22 @@
-# Open Security Controls Assessment Language (OSCAL) 
+# Open Security Controls Assessment Language (OSCAL)
 
 > Current work is happening in the [master](https://github.com/usnistgov/OSCAL/) branch.
 
 NIST is developing the Open Security Controls Assessment Language (OSCAL), a set of hierarchical, formatted, XML- and JSON-based formats that provide a standardized representation for different categories of information pertaining to the publication, implementation, and assessment of security controls. OSCAL is being developed through a [collaborative approach](https://github.com/usnistgov/OSCAL/blob/master/CONTRIBUTING.md) with the public. Public contributions to this project are welcome.
 
+With this effort, we are stressing the agile development of a *minimal* format that is both generic enough to capture the breadth of data in scope (controls specifications), while also capable of ad-hoc tuning and extension to support peculiarities of both (industry or sector) standard and new control types.
+
 The [OSCAL website](https://pages.nist.gov/OSCAL/) provides an overview of the OSCAL project, including an XML and JSON [schema reference](https://pages.nist.gov/OSCAL/schema/), [examples](https://pages.nist.gov/OSCAL/examples/), and other resources.
 
-This repository consists of the following directories pertaining to the OSCAL project:
+This repository consists of the following directories and files pertaining to the OSCAL project:
 
-  * [docs](docs): Documentation graphics, prose, progress updates, and presentation slides
-  * [examples](examples): OSCAL examples, including both demo (unit test) and "real world" examples
-  * [schema](schema): OSCAL schemas and validation tools
-  * [sources](sources): Resources used to produce OSCAL artifacts that are not maintained by the OSCAL project (e.g., a copy of the NIST SP 800-53 control data feed schema)
-  * [working](working): Development artifacts (e.g., XML, XSLT, CSS, script, Markdown, and sample files, plus supporting files); additional documentation is posted under [working/doc](working/doc): 
+* [.github](.github): This directory holds GitHub issue and pull request templates for the OSCAL project.
+* [docs](docs): This directory contains a variety of documentation files and artifacts. They include copies of graphics, old drafts of documentation pending conversion to the new documentation format, and detailed documentation for the OSCAL schema, including a tag library.
+* [examples](examples): This directory contains numerous OSCAL examples in both XML and JSON formats. Some examples are considered provisional "finished" versions of OSCAL catalogs and profiles; they are not authoritative but are intended as demonstrations of OSCAL. Other examples are works in progress. Each subdirectory within the examples directory clearly indicates the current status of its example files.
+* [lib](lib): This directory contains a variety of supporting files. For example, it holds core XSLT stylesheets for processing OSCAL. It also contains scripts and utilities used internally by the OSCAL developers.
+* [schema](schema): This directory contains the OSCAL schemas and related validation tools. The directory contains both XML and JSON representations for OSCAL.
+* [sources](sources): This directory contains copies of resources not maintained by the OSCAL project that have been used as sources for producing OSCAL artifacts. For example, the sources directory has a copy of the NIST SP 800-53 control data feed schema.
+* [working](working): This directory contains development artifacts that comprise the implementation of the OSCAL catalog and profile layers. Examples of artifact types in this directory include XML, XSLT, CSS, script, Markdown, and sample files, plus supporting files.
+* [CONTRIBUTING.md](CONTRIBUTING.md): This file is for potential contributors to the OSCAL project. It provides basic information on the OSCAL project, describes the main ways people can make contributions, explains how to report issues with OSCAL, and lists pointers to additional sources of information. It also has instructions on establishing a development environment for contributing to the OSCAL project and using GitHub project cards to track development sprints.
+* [LICENSE.md](LICENSE.md): This file contains license and copyright information for the files in the OSCAL GitHub repository.
+* [USERS.md](USERS.md): This file explains which types of users are most likely to benefit from consuming OSCAL tools and content when they are available.

docs/README.md

@@ -1,85 +1,8 @@
 # OSCAL Documentation Materials
 
-This part of the repository contains OSCAL documentation and related supporting files.
+This directory contains OSCAL documentation and related supporting files. Its structure and contents are as follows:
 
-The 'docs' subdirectory contains the following:
-
- * '[graphics](graphics)' - graphics files for reference by OSCAL documentation, and source files for generating particular graphics
- * '[presentations](presentations)' - Microsoft Powerpoint slides for OSCAL presentations, some with notes
- * '[prose](prose)' - Prose files (e.g., Markdown format) with narrative on OSCAL (OSCAL overview, how-to steps, etc.)
- * '[schema](schema)' - OSCAL schema documentation, as further detailed in [schema/readme.md](schema/readme.md)
-
-# PROGRESS UPDATES (also sent via email)
-NOTE SENT ON SEPTEMBER 26, 2017:
---------------------------------
-We have been working on creating documentation for the OSCAL project. We have prepared drafts of an overview document that mirrors much of the same content from the PowerPoint slides we delivered at the last tiger team meeting. We have also developed documentation for all of the tags used in the current OSCAL model.
-
-These documents can be found on GitHub using the following links:
-
-- Overview: https://github.com/usnistgov/OSCAL/blob/master/docs/prose/OSCAL%20Overview.md
-- Tag Library: https://github.com/usnistgov/OSCAL/blob/master/working/doc/schema/oscal-tag-library.md
-
-You will need privileges to view the private OSCAL GitHub repository to access these documents. Please send an email to [email protected] or [email protected] including your GitHub username to request access to the OSCAL repository.
-
-We would appreciate your review and comments on these documents, with a specific focus on the organization and usability of this documentation. We have created a comment template for this purpose which can be found at: https://github.com/usnistgov/OSCAL/blob/master/docs/OSCAL-comment-template.xls?raw=true. Please email your comments using this template to [email protected]. To allow time for us to consider your comments in the next sprint work, please email your comments by Monday, October 9th, 2017.
-
-We plan to use your feedback to continuously improve the documentation for the project. We plan to ask for periodic reviews of this and other documentation, examples, and schema in the future as our work progresses.
-
-NOTE SENT ON OCTOBER 26, 2017:
--------------------------------
-We accomplished the following in sprint 4:
-- Issue #25: Updated and organized project documentation on Github. We have updated the top-level readme and readmes in the docs and working folders. I have also posted an updated presentation on OSCAL in the presentations folder.
-https://github.com/usnistgov/OSCAL 
-https://github.com/usnistgov/OSCAL/tree/master/docs/presentations 
-
-- Issue #42: Working on closing out and cleaning up any outstanding issues on Github that have been addressed. We will continue to do this through sprint 5.
-https://github.com/usnistgov/OSCAL/issues 
-
-- Issue #28: Ongoing improvements based on community feedback. We are continuing to request feedback on the documentation within the Github project. Please send comments to [email protected]. We have created a comment template for this purpose which can be found at:
- https://github.com/usnistgov/OSCAL/blob/master/docs/OSCAL-comment-template.xls?raw=true 
-
-- Issue #43: We have added support for advanced tailoring of catalog profile. We are working on completing support for extending profiles, filtering controls to include, adding and modifying statements within a control, and setting control parameters. We will be building examples in sprint 5 to illustrate this new functionality.
-
-- Issue #5: Designing an approach for incorporating frameworks (e.g., NIST Cybersecurity Framework, PCI DSS, HIPPA, etc) into OSCAL. We have developed a set of user stories which we will be exploring in future sprints to add this functionality to OSCAL.
-
-For sprint 5 will be working on the following:
-
-- Continued enhancement of profile tailoring capabilities. We are going to develop OSCAL profiles for the FedRamp low, moderate, and high baselines. We hope that many of the new tailoring features will be used as part of these new profiles.
-- Expansion of OSCAL examples. We will be organizing and adding a bunch of simple examples of using the OSCAL format.
-- Integration of JSON schema and examples for OSCAL.
-
-We welcome your feedback on this work. We hope to use your comments on OSCAL documentation, examples, and schema in our ongoing work to make improvements to the project. Please either post to this list or send feedback to [email protected].
-
-NOTE SENT ON DECEMBER 6, 2017:
-------------------------------
-The team worked diligently to make more progress and advance OSCAL development.
-We wrapped up 2 more sprints: 4 (October) & 5 (November). A summary of Sprints 4 and 5 is below.
-
-By the end of Sprint 3, we had a prototype catalog format and examples of several different kinds of catalogs (NIST SP800-53/A; ISO/IEC 27001/2; COBIT 5) encoded in this format and valid to its schemas and defined constraints. We had also begun to extend our prototype design to encode not only catalogs, but profiles, as a formal XML document type. The "profile" data representation ("tagging") aims to be comprehensive, legible and succinct in describing (a) the selection (via inclusion/exclusion) of controls and ‘subcontrols’ from catalogs (one or many) into a profile, and (b) modifications or conditions to be applied to those controls, especially but not limited to the setting of parameter values for inclusion (substitution/insertion) into controls in application. Describing this "delta" (between a control catalog, and its application or invocation) in an external form (namely, as an OSCAL profile) externalizes the relationship between a profile and its source(s), rendering it traceable and reversible.
-
-Sprints 4 and 5 were devoted to building out support for this model in the form of transformation logic to "resolve" a profile against its catalog (demonstrating the viability of our model by testing in an implementation), along with a range of subordinate transformations and validations related both to catalogs and profiles. These continue to be developed "under load" while we build out example data sets, both real-world and lab ("pathological") cases for testing. Simultaneously, the engagement of a new team member has enabled us to start exploring ways of exposing OSCAL data in JSON, for consuming applications.
-
-In more detail, our efforts included:
-Continuing to refine OSCAL data models, esp relating to profiles
-Refinement and testing a profile resolution prototype (profiling semantics in operation). A demo embeds this logic (XSLT) in a rendition pipeline whose final outputs are a readable HTML 'paste-up' of the catalog with the profile's emendations.
-Continual regression testing (coevolution) of validations (schema and Schematron) against stable samples
-Continuing refinement of Schematron validations of extra-schema constraints over OSCAL (both general- and special-purpose)
-Refinement and testing of SP800-53 baselines HIGH, MODERATE and LOW, expressed as OSCAL profiles (of rev4 catalog in OSCAL)
-Early/experimental casting FedRAMP and CSF data sets into OSCAL (referencing SP800-53 rev4 and its baselines)
-Refining FedRAMP "shells" (partial/demo versions, but with live data) expressing three example FedRAMP specifications as OSCAL profiles of SP800-53 baselines (which are profiles of a catalog) - so, two layers of profile resolution not just one
-Building out and commenting unit testing (miniature specimen) OSCAL data set - 'mini-testing' catalog and profiles
-Testing SP800-53 NVD XML -> OSCAL conversion on SP800-53 rev 5 (draft)
-Developing, testing and running prototype JSON conversion scripts capable of representing core OSCAL artifacts (including catalogs and profiles) in JSON syntax (by supporting bidirectional conversion)
-Renaming and reorganizing for accessibility
-
-Results include (see the Github repository https://github.com/usnistgov/OSCAL (still private but to get access please send me an email with your GitHub ID):
-
-Updated schemas, Schematrons and related artifacts in a /schema subdirectory, including /schema/xml and /schema/json branches
-High-level documentation including tag library remains in /docs
-A new /examples directory, with examples
-Examples include SP800-53 rev4 with its baselines; FedRAMP "rough cast" examples (extraction/mapping of FedRAMP specifications as OSCAL profiles); 'mini-testing' (OSCAL unit tests)
-JSON versions of all these (still in a pull request at time of writing), with 'round-trip' demo XML coming back
-These supplement, but do not replace, examples kept in /working
-HTML 'published' (resolved-and-rendered versions) of catalogs and profiles are now always in a 'pub' directory
-
-Everything can be found in the Sprint 5 branch (committed).
+ * [graphics](graphics): This directory contains graphics files referenced within OSCAL documentation and source files for generating particular graphics.
+ * [prose](prose): This directory contains draft prose files (e.g., Markdown format) regarding the "bleeding edge" of OSCAL development. The directory also holds various HTML files that bring together numerous diagrams and text to explain the current thinking on certain aspects of OSCAL development.
+ * [schema](schema): This directory contains documentation, in OSCAL XML format, of the OSCAL schema and related resources such as Schematron constraint sets. Of particular note is the OSCAL tag library file, which contains element definitions.
+ * [OSCAL-comment-template.xls](OSCAL-comment-template.xls): This file is a Microsoft Excel spreadsheet previously used for submitting comments on OSCAL documentation in Markdown format.