Documentation Updates

Open
#12 8 comments 2 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Active
Tech stack
openapi, react

Research direction

Start by reviewing the existing model, schema, ADRs, and roadmap pages linked in the issue to map the current information architecture. The requested work spans navigation, search, user-oriented schema guidance, GitHub links, and roadmap references; done would require agreed scope and success criteria for the selected improvements.

Written by the indexing model from the issue text.

Description

enhancement Stale
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

Dominant language
Go
Stars
0
Forks
11
Avg merge
22h 49m
Merged PRs (30d)
18

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from gemaraproj/website

All issues in gemaraproj/website

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.