Skip to content

Refactor analysis documentation and improve clarity - #13

Merged
brian-ruf merged 7 commits into
mainfrom
docs/clear-language-wip-banner
Sep 10, 2026
Merged

brian-ruf merged 7 commits into
mainfrom
docs/clear-language-wip-banner

Conversation

@pjavan

@pjavan pjavan commented Sep 9, 2026

Copy link
Copy Markdown
Collaborator

This pull request updates the README.md and the analysis HTML page to clarify documentation, improve consistency, and add details about the "Work in progress" banner behavior for analyses. The changes focus on making descriptions more concise, updating terminology, and documenting new UI behavior for analysis status.

Documentation improvements and clarifications:

  • Rewrote and condensed descriptions throughout README.md for clarity, including the project overview, purpose, and repository structure. This includes clarifying the role of the OSCAL Foundation, simplifying section explanations, and updating terminology (e.g., "Contents" instead of "What it holds").
  • Updated the "Analyses" section to clarify how analyses are managed, how registry entries work, and the policy for superseding analyses.
  • Improved instructions for running the site, specifying the use of static servers, clarifying the use of the Live Preview extension, and updating task descriptions. [1] [2]
  • Added a detailed explanation of the "Work in progress" banner: when it appears, how it is dismissed, session behavior, and how to check for regressions.
  • Updated contribution guidelines to emphasize practical, organized examples.

Analysis UI and metadata updates:

  • Added a "Work in progress" banner (<aside class="wip-banner">) to the analysis HTML page (assessment-first.html) that is shown based on analysis status.
  • Updated the meta description and Open Graph/Twitter metadata for the analysis to better reflect the content and align with new terminology.

These changes improve the clarity, usability, and maintainability of the documentation and analysis presentation.- Updated the question in the analysis JSON for better specificity regarding OSCAL models and automated checks.

  • Revised meta descriptions and content in index.html files for analyses, patterns, and recommendations to enhance clarity and consistency.
  • Improved the wording in the lede paragraphs across various HTML files to better convey the purpose of each section.
  • Added a new JavaScript file for regression checks related to analysis-scoped progress notices, ensuring proper functionality and coverage.
  • Enhanced error messages and handling in the site.js file for better user experience during loading failures.

- Updated the question in the analysis JSON for better specificity regarding OSCAL models and automated checks.
- Revised meta descriptions and content in index.html files for analyses, patterns, and recommendations to enhance clarity and consistency.
- Improved the wording in the lede paragraphs across various HTML files to better convey the purpose of each section.
- Added a new JavaScript file for regression checks related to analysis-scoped progress notices, ensuring proper functionality and coverage.
- Enhanced error messages and handling in the site.js file for better user experience during loading failures.
- Updated six-questions.json to clarify rule requirements.
- Modified bannercheck.js to use CSS variables for styling.
- Added source_path function in extract.py for better file resolution.
- Enhanced pagecheck.js to ensure snippet accessibility.
- Improved verify.py with better command descriptions and offline handling.
- Introduced schema_evidence.py for refreshing schema fragments from NIST.
- Created schema_validation.py to validate NIST schemas with Unicode support.
- Added test_verify.py for regression testing of the verifier without external dependencies.
- Removed markdown snippets from the manifest, ensuring all entries are OSCAL JSON.
- Updated `package.py` to clarify the handling of excluded files and maintain alignment with the package structure.
- Enhanced `pagecheck.js` to improve clarity in comments and checks for quotation and attribution hooks.
- Revised `scenario_page.py` to simplify comments regarding option-letter order.
- Modified `test_verify.py` to enforce that only OSCAL JSON snippets are included and to ensure editorial checks do not allow background attribution.
- Updated `verify.py` to clarify checks for editorial references and ensure no background document attribution is present in editorial data.
- Replaced direct extraction calls with a new source_inputs module to manage source paths and integrity checks.
- Implemented a source lock JSON file to define and validate source configurations.
- Enhanced error handling in OSCAL artifact processing to provide clearer feedback on source issues.
- Added comprehensive unit tests for source input management, ensuring robustness against various edge cases.
- Updated existing tests to align with the new source input structure and validation logic.
…technical hardening guidance. Necessary to fix broken tests with dependencies that would not resolve from internet connections.
@brian-ruf
brian-ruf merged commit c5c81dc into main Sep 10, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants