Docs redesign sprint19 (#19)

* Improvements to high-level schema docs / overview

* Improved text in the docs

* New hero graphic

* Repaired small glitches preventing file loading

* Adjusting hero graphic scale; removing unwanted graphics

* Slight changes to home page: more concise, better screen layout

docs/content/documentation/components/index.md

@@ -7,16 +7,22 @@ layout: post
 topnav: documentation
 sidenav: documentation
 subnav:
-  - text: Catalog
-    href: /docs/components/catalog/
   - text: Control
     href: /docs/components/control/
+  - text: Catalog
+    href: /docs/components/catalog/
   - text: Profile
     href: /docs/components/profile/
 sticky_sidenav: true
 ---
 
-The plans for OSCAL involve all the components depicted in the following diagram:
+OSCAL, or any security documentation using current best practices, is all about **controls** and **catalogs**. A control represents a security requirement, guideline, procedure or activity. A catalog is an organized collection of controls.
+
+However, both controls and catalogs represent abstractions. In order to apply these ideas to real systems, we need documents that talk about the real world. The other layers of OSCAL's model together make up a component architecture that enables such application, through the Risk Management Framework up from policy definition (layers 1 and 2), planning and authorization (on OSCAL layer 3, the Implementation layer), and through to Assessment and Assessment Results (on layers to come).
+
+Specifically, the design of the Profile layer, in relation to the Catalog layer, reflects the use of control catalogs as outlined in NIST SP800-53 -- specifically the design of "baselines" and "overlays" over a base catalog. (And then, as we see in the real world, overlays on the overlays.) In OSCAL, this idea is generalized to be applicable to any set of information presented in catalog form. Thus the idea of tailoring in application can be applied not only to security guidelines in general, but also in mixed environments that have to address requirements in more than one catalog at a time.
+
+All these components except controls (which are present in all layers) are depicted in the following diagram:
 
 <img src="/assets/img/oscal-components.png" alt="oscal components" width="800" />
 

docs/content/documentation/schemas/index.md

@@ -8,26 +8,39 @@ sidenav: schemas
 sticky_sidenav: true
 ---
 
-## About the Sample Schemas
+## About the schemas
 
-### Design Principles for Sample Schemas
+Each OSCAL **model** comes with an XSD and a corresponding JSON Schema.
+
+### XML and/or JSON
+
+The OSCAL project is producing schemas to describe and validate data in two formats, XML and JSON. These are produced within a framework that provides for semantic unification in the form of a meta-model, which is subsequently expressed (written out) into two different expressions:
+
+* An XSD (W3C XML Schema) that describes an XML tag set
+* A JSON Schema (v7) that describes a JSON data object
+
+XML documents that are conformant (validate) to an OSCAL XSD can be converted without loss into the corresponding JSON, according to a mapping provided by the metamodel, and vice versa. Accordingly we can produce not only the models and their documentation, but also tools for converting data sets in the respective formats into their "opposites".
+
+In addition to the improved control over modeling and documentation this architecture gives us, this enables OSCAL to serve the needs of developers who use either or both formats. We hope and expect that developers' experience with different approaches will inform further efforts to unify and consolidate a coherent data model.
+
+In future, we plan to extend our models with mappings to other formats as well. As a superset of JSON, YAML syntax is an attractive candidate, as is a Markdown application. Once we have demonstrated that the models themselves are adequate to the data, many more things become possible.
+
+### Design principles for the schemas
 The sample schemas have been created with the following design principles in mind:
 
 - Simplicity and ease of use.
-- Relevance for typical producers. The basic schemas bring to the foreground the functionality that producers typically use. The entire set of schemas provides a foundation upon which one can expand to illustrate additional functionality.
+- Relevance for typical producers.
 - Extensibility. The sample schemas are designed for adaptability and extensibility. In ordinary cases, users and designers of application can introduce new constructs and usages to support local requirements. In special cases, new schemas may be constructed to work with schemas already in use.
 
-### Producer Benefits of Sample Schemas
-
-Benefits provided by the sample schemas include the following:
 
-#### Continuity of context.
+### Schema documentation
 
-#### Usability
+Find documentation for each of the models linked on the left.
 
-#### Quality
+Additionally, a separate page describes the 
+[OSCAL Prose Model](/docs/schemas/oscal-prose/), which is shared by each of the component models.
 
-## Available Schemas
+### Currently available
 
 - Catalog XML Schema (hyperlink to: https://pages.nist.gov/OSCAL/schema/#catalog-xml-schema)
 - Catalog JSON Schema (hyperlink to: https://pages.nist.gov/OSCAL/schema/#catalog-json-schema)

docs/content/documentation/schemas/oscal-prose.md

@@ -22,7 +22,7 @@ In addition, there are contexts in OSCAL where prose usage may be further constr
 
 ## Markdown compatibility
 
-OSCAL also maintains a mapping from its HTML-like tagging for prose into a Markdown syntax. This mapping is shown below. Since markdown (as an array of string objects) is our syntax of choice for representing unstructured prose in JSON, transparent and lossless bidirectional mapping between the OSCAL markup (tag) representation, into its Markdown equivalent, is a requirement.
+OSCAL also maintains a mapping from its HTML-like tagging for prose into a Markdown syntax. Since markdown (as an array of string objects) is our syntax of choice for representing unstructured prose in JSON, transparent and lossless bidirectional mapping between the OSCAL markup (tag) representation, into its Markdown equivalent, is a requirement.
 
 When in doubt, we look to CommonMark for guidance on syntax, largely because it is more rigorously tested than many others.
 

docs/content/home.md

@@ -5,17 +5,18 @@ permalink: /
 layout: home
 
 hero:
-  image: /assets/img/security-hero4.jpg
+  image: /assets/img/automation-hero.png
   callout:
-    alt: "OSCAL:"
-    text: Documentary Foundations for Systems Security
+#    alt: "OSCAL:"
+#    text: Documentary Foundations for Systems Security
+     text: More Insight, Less Paper
   button:
     href: /getinvolved/
     text: Get Involved
   link:
     text: Learn more about OSCAL
     href: /learnmore/
-  content: OSCAL provides standard data formats for automation of systems security assessments and continuous monitoring.
+  content: Standard data formats for systems security planning, assessment and monitoring.
 
 tagline: A “Standard for Standards” for Automating Security Assessment & Continuous Monitoring
 intro: |

docs/content/learnmore/assessors.html

@@ -10,16 +10,14 @@
 
 <div>
 <p><strong><em>Audit and assessment personnel who validate the accuracy of security plans and assess the implementation of security controls within information systems.</em></strong></p>
-  <p>OSCAL standardizes documentation of security controls within a specific profile, while establishing a framework for information systems to attest programmatically to the state of the security controls being addressed.</p>
+  <p>OSCAL standardizes the format for documentation of security controls, while establishing a framework for the automated assessment of information systems to be evaluated based the state of the security controls being addressed.</p>
   <h3>How Does OSCAL Help Me?</h3>
 <ul>
   <li>
   <p>Reduces the amount of manual labor need to assess the implementation of controls.</p></li>
   <li>
-  <p>Permits flexibility through profiling for tailoring baselines to a set of appropriate controls for any agency information system.</p></li>
+  <p>Provides ongoing, automated assessment of an information systems assurance, allowing any drift in control implementation to be detected as it occurs, reducing overall risk.</p></li>
   <li>
-  <p>Provides real-time or near real-time assurance programmatically, allowing any security drift to be detected earlier and reducing overall risk.</p></li>
-  <li>
-  <p>Enables mapping standard catalogs of controls to common profiles, reducing the number of assessments required to ensure compliance with multiple frameworks.</p></li>
+  <p>Enables mapping standard catalogs of controls and common baselines, to system implmentations, reducing the number of assessments required to ensure compliance with multiple frameworks.</p></li>
 </ul>
-</div>
+</div>

docs/content/learnmore/contentcreators.html

@@ -10,16 +10,16 @@
 
 <div>
 <p><strong><em>Systems security policy professionals who set requirements for security programs, both across and within organizations and agencies</em></strong></p>
-  <p>OSCAL provides a standard solution for building security profiles that set the expectations for implementation within the program and associated information systems.</p>
+  <p>OSCAL provides a standardized solution for building security baselines, through the use of OSCAL profiles, that set the expectations for control implementation within one or more programs and associated information systems.</p>
   <h3>How Does OSCAL Help Me?</h3>
 <ul>
   <li>
   <p>Ensures consistency of control implementation across the enterprise.</p></li>
   <li>
-  <p>Improves the transparency of policy implementation by automating assessment.</p></li>
+  <p>Improves the transparency of policy implementation by automating reviews of security control implementation and assessments.</p></li>
   <li>
-  <p>Permits market-based development of shared profiles, working across agencies, compliance frameworks and domains.</p></li>
+  <p>Permits market-based development of shared OSCAL profiles, working across agencies, compliance frameworks and domains.</p></li>
   <li>
-  <p>Improves the Machine Experience (MX) for vendors in implementing enterprise-specific policies by representing them in a standards-based format.</p></li>
+  <p>Improves the Machine Experience (MX) for vendors in implementing enterprise-specific policies by representing them in a standardized format.</p></li>
 </ul>
-</div>
+</div>

docs/content/learnmore/index.md

@@ -10,13 +10,13 @@ sticky_sidenav: true
 
 ## What is OSCAL?
 
-NIST is developing the Open Security Controls Assessment Language (OSCAL) standard and data-centric framework that can be applied to an information system for documenting and assessing its security controls. Today, security controls and profiles are represented in proprietary ways and are expressed in prose format rather than being machine readable. This can lead to imprecise implementation and differences in interpretation, and requires manual effort to implement the controls. An important goal of OSCAL is to move the security controls and profiles from a text-based and manual approach (using word processors or spreadsheets) to a standardized and machine-readable format that improves both the User Experience (UX) and Machine Experience (MX) of system security planning, assessment and authorization. With standard, authoritative reference data sets encoded in OSCAL, along with the support of automated processes, security professionals will be able to do better work with less effort.
+NIST is developing the Open Security Controls Assessment Language (OSCAL) as a standardized, data-centric framework that can be applied to an information system for documenting and assessing its security controls. Today, security controls and control baselines are represented in proprietary ways and are expressed in prose format rather than being machine readable. This can lead to imprecise differences in interpretation, and requires manual effort to implement the controls. An important goal of OSCAL is to move the security controls and control baselines from a text-based and manual approach (using word processors or spreadsheets) to a set of standardized and machine-readable formats that improve both the User Experience (UX) and Machine Experience (MX) of system security planning, assessment and authorization. By representing control information in OSCAL, providing authoritative reference data sets, this information can better support automated processes allowing security professionals will be able to do better work with less effort.
 
 ## Why OSCAL?
 
-There are a number of factors contributing to the challenge faced by information system security professionals today: multiple regulatory compliance standards and frameworks ([NIST FISMA](https://www.nist.gov/programs-projects/federal-information-security-management-act-fisma-implementation-project), [PCI](https://www.pcisecuritystandards.org/pci_security/), [HIPAA](https://www.hhs.gov/hipaa/index.html), [ISO 27001](https://www.iso.org/isoiec-27001-information-security.html) etc.), which change over time; their overlapping scope and the requirement to manage them together; and the size, complexity and ongoing development of the systems being documented. To provide assurance of a system's compliance posture, the implementation of security systems must be both correctly described, and validated against relevant security controls. This is resource-intensive and often infeasible within budget constraints given the complexity of the problem.
+There are a number of factors contributing to the challenges faced by information system security professionals today: multiple regulatory compliance standards and frameworks (e.g., [NIST FISMA](https://www.nist.gov/programs-projects/federal-information-security-management-act-fisma-implementation-project), [PCI](https://www.pcisecuritystandards.org/pci_security/), [HIPAA](https://www.hhs.gov/hipaa/index.html), [ISO 27001](https://www.iso.org/isoiec-27001-information-security.html)), which change over time; their overlapping scope and the requirement to manage them together; and the size, complexity and ongoing development of the systems being documented. To provide assurance of a system's compliance posture, the implementation of security systems must be both correctly described, and validated against relevant security controls. This is resource-intensive and often infeasible within budget constraints given the complexity of the problem.
 
-The ability of OSCAL to streamline and standardize the security documentation, implementation, and assessment process will reduce complexity, decrease implementation costs, and enable the continuous assessment of system security against multiple sets of requirements simultaneously. This approach has the added benefit of significantly reducing the paperwork associated with current processes, helping government agencies meet the goals of the [Paperwork Reduction Act](https://en.wikipedia.org/wiki/Paperwork_Reduction_Act).
+The ability of OSCAL to streamline and standardize the security control documentation, implementation, and assessment process will reduce complexity, decrease implementation costs, and enable the continuous assessment of system security against multiple sets of requirements simultaneously. This approach has the added benefit of significantly reducing the paperwork associated with current processes, helping government agencies meet the goals of the [Paperwork Reduction Act](https://en.wikipedia.org/wiki/Paperwork_Reduction_Act).
 
 ## How OSCAL Supports Your Role
 

docs/content/learnmore/securitypros.html

@@ -10,20 +10,18 @@
 
 <div>
 <p><strong><em>Security professionals who document or implement security controls within information systems.</em></strong></p>
-  <p>OSCAL provides a standard for documenting security and privacy controls that maps across multiple compliance frameworks (i.e. NIST, PCI, etc.) and a method for attesting to the implementation of the controls within information systems</p>
+  <p>OSCAL provides a standardized format for documenting security and privacy controls that maps across multiple compliance frameworks (i.e. NIST, PCI, etc.) and a method for attesting to the implementation of the controls within information systems</p>
   <h3>How Does OSCAL Help Me?</h3>
 <ul>
   <li>
   <p>Enables continuous maintenance of control documentation within a framework designed for that purpose.</p></li>
   <li>
-  <p>Permits the centralization of configuration management within and across security documentation and applications; this can reduce the attack surface and make it easier to implement controls for least privilege.</p></li>
-  <li>
   <p>Reduces the amount of paperwork required to implement multiple compliance frameworks.</p></li>
   <li>
   <p>Ensures that security as proposed and planned (defined in the controls) matches with security as implemented, with less need for manual assessments.</p></li>
   <li>
   <p>Flattens the learning curve for new staff by enabling them to focus on problems not technology.</p></li>
   <li>
-    <p>Enables mapping standard catalogs of controls to common profiles, reducing the number of assessments required to ensure compliance with multiple frameworks.</p></li>
+    <p>Enables mapping standard catalogs of controls to common control baselines, implemented as OSCAL profiles, reducing the number of assessments required to ensure compliance with multiple frameworks.</p></li>
 </ul>
 </div>

docs/content/learnmore/toolvendors.html

@@ -12,19 +12,16 @@
   <p><strong><em>Tool developers who build security compliance systems (Electronic
       Governance Risk and Compliance [eGRC] systems) or who provide secure infrastructure/software
       solutions to the Federal Government or to highly regulated industries</em></strong></p>
-  <p>OSCAL provides a standard for consuming control, catalog, profile, and implementation
-    data to visualize and automate security compliance processes. Provides an assessment standard
-    for infrastructure and software solutions to attest to their security control implementation in
-    an automated manner.</p>
+  <p>OSCAL provides standardized formats for consuming control, catalog, profile, and implementation
+    information to visualize and automate security compliance processes. Provides a standardized means for the automated assessment of infrastructure and software solutions to attest to their security control implementation.</p>
   <h3>How Does OSCAL Help Me?</h3>
   <ul>
     <li>
       <p>Use automated tools to create more complete and consistent security plans with machine assistance.</p></li>
     <li>
-      <p>Easily attest to the state of controlimplementations, reducing the paperwork burden associated with serving
-        federal agencies.</p></li>
+      <p>Easily attest to the state of control implementations, reducing the paperwork burden associated with supporting federal agencies.</p></li>
     <li>
-      <p>Expose security control and assessment data in a standard specification which can be represented via JSON or
+      <p>Expose security control and assessment data in a standardized format which can be represented via JSON or
       XML.</p></li>
     <li>
       <p>Improve the User Experience (UX) and Machine Experience (MX) by offering
@@ -35,6 +32,6 @@ <h3>How Does OSCAL Help Me?</h3>
         speeding market adoption within the federal sector and highly regulated industries.</p></li>-->
     <li>
       <p>Minimizes the need for vendors to customize solutions for customers by adhering to a
-        broad-based standard.</p></li>
+        broad-based set of standardized formats.</p></li>
   </ul>
 </div>

docs/content/resources/index.md

@@ -11,7 +11,7 @@ layout: post
 ## Useful Links
 
 * [GitHub Repository for OSCAL](https://github.com/usnistgov/OSCAL)
-* [Computer Security Resource Center: OSCAL](https://csrc.nist.gov/Projects/Open-Security-Controls-Assessment-Language)
+* [NIST Computer Security Resource Center: OSCAL](https://csrc.nist.gov/Projects/Open-Security-Controls-Assessment-Language)
 
 ## Tools