Documentation Updates

[trevor-vaughan]

Is your feature request related to a problem?

I was walking through the Gemara spec via the website and found it difficult to discover all of the information that I needed to use the spec effectively.

Describe the solution you'd like

Navigation

• I would like to be able to easily view all attributes and relationships of the spec on the website
  • A translation from CUE -> OpenAPI -> Docusaurus+React Flow may be a potential solution for a more interactive experience
• I would like to be able to easily search the site
• I expected to be able to drill down into the different layers of the model to be able to see the associated schema materials

Missing Content

• The ADRs page doesn't contain a list of ADRs (maybe there haven't been any)
• When looking at the schema page, it isn't immediately obvious as to when/why I would use parts of the schema. User-oriented flows starting from "what problem does this flow solve" would be great

Nits

• I would suggest placing a GitHub icon link at the top right of the page (I looked for it instinctively to file this ticket)
• If the Roadmap linked back to the driving GitLab issues (or other artifacts) it would be useful for understanding the overall state of things and where I might contribute most effectively

Describe alternatives you've considered

No response

Success Criteria

No response

Additional context

No response

[jpower432]

Thanks for the feedback! A couple items on here are quick fixes, but I think this is worth having more discussion on the suggested technology change. @eddie-knight Do you have thoughts?

The ADRs page doesn't contain a list of ADRs (maybe there haven't been any)

It is in the left hand drop down, but good feedback. It may not be an obvious place for the index.

When looking at the schema page, it isn't immediately obvious as to when/why I would use parts of the schema. User-oriented flows starting from "what problem does this flow solve" would be great.

We have tutorials, but they are not discoverable from the schema pages. https://gemara.openssf.org/tutorials/. Do the tutorials provide what you are looking for? Were you expecting to see a link from a particular schema to its tutorial?

If the Roadmap linked back to the driving GitLab issues (or other artifacts) it would be useful for understanding the overall state of things and where I might contribute most effectively

Good suggestion. We have a GitHub Project that could be linked to that page here.

[trevor-vaughan]

It is in the left hand drop down, but good feedback. It may not be an obvious place for the index.

Ah! When I clicked on the quick links, it took me to the page. I expected it to expand when I was already on the page and missed that I needed to click the triangle precisely.

We have tutorials, but they are not discoverable from the schema pages. https://gemara.openssf.org/tutorials/. Do the tutorials provide what you are looking for? Were you expecting to see a link from a particular schema to its tutorial?

I think what I'm missing in the tutorials is a sample system to help me put it all in context. For example, on the Threat Assessment page, I'm assessing a threat to something from something (maybe via an existing Threat Model).

[trevor-vaughan]

Digging through the ADRs and have some questions:

• When was the decision made?
• Who were the people that accepeted the proposal?
• What was the last review date of the decision?
• When will the decision need to be reviewed again?

The last two may be overkill but the first two seem like important information

[jpower432]

Digging through the ADRs and have some questions:

• When was the decision made?
• Who were the people that accepeted the proposal?
• What was the last review date of the decision?
• When will the decision need to be reviewed again?

The last two may be overkill but the first two seem like important information

The first two are captured through the PR process, but not in the ADR itself. I don't think we have had a need so for for a formal ADR review process.

[trevor-vaughan]

The original PR works. Would it be possible to link back to the PR then? From the website, I expected to get back to whatever the relevant information was from the ADR itself.