Skip to content

docs: adds an initial FAQ page to the website#402

Open
jpower432 wants to merge 4 commits into
gemaraproj:mainfrom
jpower432:docs/faq
Open

docs: adds an initial FAQ page to the website#402
jpower432 wants to merge 4 commits into
gemaraproj:mainfrom
jpower432:docs/faq

Conversation

@jpower432

@jpower432 jpower432 commented May 5, 2026

Copy link
Copy Markdown
Contributor

Description

Add FAQ page covering getting started, artifact explanations, OSCAL relationship, adoption guidance, and team workflows.

Schema Changes

Schema Changes Made

  • No schema changes
  • Audit Log schema (auditlog.cue) changes
  • Capability Catalog schema (capabilitycatalog.cue) changes
  • Control Catalog schema (controlcatalog.cue) changes
  • Enforcement Log schema (enforcementlog.cue) changes
  • Evaluation Log schema (evaluationlog.cue) changes
  • Guidance Catalog schema (guidancecatalog.cue) changes
  • Mapping Document schema (mappingdocument.cue) changes
  • Policy Document schema (policy.cue) changes
  • Principle Catalog schema (principlecatalog.cue) changes
  • Risk Catalog schema (riskcatalog.cue) changes
  • Threat Catalog schema (threatcatalog.cue) changes
  • Vector Catalog schema (vectorcatalog.cue) changes
  • Other

Schema Change Details

<!-- If applicable, provide a brief summary or example of schema changes -->

Testing

  • Unit tests added/updated
  • Manual testing performed
  • Test data updated (if applicable)

Related Issues

Closes #74

Reviewer Hints

Self-review checklist

  • This PR has content that was created with AI assistance.
  • I have the experience and knowledge necessary to answer maintainer questions about the content of this PR, without using AI.

jpower432 and others added 2 commits May 4, 2026 20:42
@jpower432 @cursoragent
docs: add FAQ page with reviewer feedback
1b64edc 
Add FAQ page covering getting started, artifact explanations, OSCAL
relationship, adoption guidance, and team workflows. Includes
navigation entry.

Incorporates reviewer feedback: add "best practices" to Layer 1 job
description and simplify OSCAL export explanation.

Assisted-by: Cursor (claude-opus-4-0526)
Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@jpower432
docs: refine FAQ content for clarity and structure
f96b9dd 
Revised FAQ section for clarity and conciseness, including updates to Layer descriptions and examples. Improved formatting and structure for easier reading.

Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com>
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 5, 2026
@jpower432 jpower432 mentioned this pull request May 5, 2026
Merged
11 tasks
hbraswelrh
hbraswelrh requested changes May 13, 2026
View reviewed changes

@hbraswelrh hbraswelrh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left several nits. There is a lot of documentation included in this PR. The existing ampel-provider and openscap-provider structure is outlined to consolidate the relevant information as a README.md.

@jpower432

jpower432 commented May 22, 2026

Copy link
Copy Markdown
Contributor Author

Left several nits. There is a lot of documentation included in this PR.

@hbraswelrh I don't see any additional comments here. Was there a technical issue with the review?

@hbraswelrh

hbraswelrh commented May 22, 2026

Copy link
Copy Markdown
Contributor

Left several nits. There is a lot of documentation included in this PR.

@hbraswelrh I don't see any additional comments here. Was there a technical issue with the review?

Nope I didn't know if you had any additional edits planned since it's in draft. Happy to approve if it's ready!

@hbraswelrh

hbraswelrh commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

@jpower432 Can you change this to "Ready for review" so I can approve? It LGTM. If it makes more sense to include an FAQ entry about the evidence field, we can add that or include it in a future PR.

@jpower432 jpower432 marked this pull request as ready for review June 15, 2026 14:57
@jpower432 jpower432 requested a review from a team as a code owner June 15, 2026 14:57
@jpower432 jpower432 requested a review from eddie-knight June 15, 2026 14:57
hbraswelrh
hbraswelrh previously approved these changes Jun 15, 2026
View reviewed changes

@hbraswelrh hbraswelrh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Approving based on my original review. This will be a living document so I think it's a great starting place.

@jpower432 jpower432 changed the title docs: adds an initial FAQ page to the website [WIP] docs: adds an initial FAQ page to the website Jun 16, 2026
eddie-knight
eddie-knight previously approved these changes Jun 17, 2026
View reviewed changes
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
@jpower432

jpower432 commented Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

@eddie-knight @hbraswelrh I actually might rework some of this even though it is approved. Took some time re-read again before merge and there are some areas that still need language refinement.

@jpower432 jpower432 marked this pull request as draft June 18, 2026 22:35
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
jpower432
jpower432 commented Jun 18, 2026
View reviewed changes
Comment thread docs/faq/index.md Outdated
@jpower432
chore: apply suggestions from code review
ed5a04b 
Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com>

Co-authored-by: Jennifer Power <jpower@redhat.com>
Signed-off-by: Jennifer Power <jpower@redhat.com>
@jpower432 jpower432 dismissed stale reviews from eddie-knight and hbraswelrh via ed5a04b June 18, 2026 22:47
@jpower432
docs: revise FAQ for OSCAL accuracy and evidence updates
3f19ffd 
Assisted-by: Claude (Anthropic, Claude Opus 4.6)
Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com>
@jpower432 jpower432 marked this pull request as ready for review June 18, 2026 23:20
@jpower432 jpower432 requested a review from hbraswelrh June 18, 2026 23:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@eddie-knight eddie-knight eddie-knight left review comments

@hbraswelrh hbraswelrh Awaiting requested review from hbraswelrh

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Clarify relationship with OSCAL

3 participants

@jpower432 @hbraswelrh @eddie-knight