Documentation for End User Developers

[ohsh6o]

As a downstream developer who wants to use FedRAMP Validations in their software product, to know how to effectively integrate it into my application and show accurate error checks like a FedRAMP reviewer, I want documentation on how to integrate the validations into my application.

Extended Description

We do have some end-user facing documentation, but it is likely time to polish it for the OSCAL 1.0.0 release and the FedRAMP PMO expectation we prep our validations release in conjunction with that.

Preconditions

• [x] FedRAMP Guidance for recommended list of programming languages for integration
• [x] Precomplied XSLT #47

Acceptance Critera

• [x] Approachable documentation for shell-based integration in Markdown file.
• [x] Approachable documentation for API-based library integration for two different languages in a Markdown file (~C#~ Java and Python maybe be best).
• [x] Explain structure and meaning of SVRL output for developers to understand how to integrate it into their application.

Story Tasks

• [x] Review existing documentation
• [x] Explore different documentation methods, decision if current is recommended

Definition of Done

• [x] Acceptance criteria met - Each user story should meet the acceptance criteria in the description
• [x] Unit test coverage of our code > 90% (from QASP) this may be fuzzy and hard to prove
• [x] Code quality checks passed - Enable html tidy with XML code standards as part of the build (from QASP)
• [x] Accessibility: (from QASP) as we create guidance or documentation and reports (semantic tagging including aria tags): demonstrate with 0 errors reported for WCAG 2.1 AA standards using an automated scanner and 0 errors reported in manual testing
• [x] Code reviewed - Code reviewed by at least one other team members (or developed by a pair)
• [x] Source code merged - Code that’s demoed must be in source control and merged
• [x] Code must successfully build and deploy into staging environment (from QASP): this may evolve from xslt sh pipline into something more
• [x] Security reviewed and reported - Conduct vulnerability and compliance scanning. threat modeling?
• [x] Code submitted must be free of medium- and high-level static and dynamic security vulnerabilities (from QASP)
• [ ] Usability tests passed - Each user story should be easy to use by target users (development community? FedRAMP FART team)
• [ ] Usability testing and other user research methods must be conducted at regular intervals throughout the development process (not just at the beginning or end). (from QASP)
• [x] Code refactored for clarity - Code must be clean, self-documenting
• [x] No local design debt
• [ ] Load/performance tests passed - test data needed - saxon instrumentation
• [x] Documentation generated - update readme or contributing markdown as necessary.
• [ ] Architectural Decision Record completed as necessary for significant design choices

[danielnaab]

I'm not certain how best to handle "Approachable documentation for shell-based integration in Markdown file". I've added notes on how to interpret a manaually-created SVRL document - but perhaps @ohsh6o had more in mind on that?

[danielnaab]

The example code in Java and Python (cross-platform C# is a challenge due to Saxon.js dependencies on .NET Framework) has been merged, and a placeholder in the UI that links to its README is here (unmerged): https://federalist-2372d2fd-fc94-42fe-bcc7-a8af4f664a51.app.cloud.gov/preview/18f/fedramp-automation/welcome-page/#/developers