Skip to content

docs(gks-vignettes): add GA4GH GKS Starter Kit vignettes doc tree#698

Draft
bencap wants to merge 1 commit into
release-2026.2.5from
docs/bencap/ga4gh-gks-vignettes
Draft

docs(gks-vignettes): add GA4GH GKS Starter Kit vignettes doc tree#698
bencap wants to merge 1 commit into
release-2026.2.5from
docs/bencap/ga4gh-gks-vignettes

Conversation

@bencap

@bencap bencap commented Jun 29, 2026

Copy link
Copy Markdown
Collaborator

This adds a standalone MkDocs site (ui/docs-gks-vignettes/) containing four GA4GH GKS Starter Kit vignettes documenting how MaveDB uses VRS, Cat-VRS, and VA-Spec in production.

This is an internal preview, not a shipping commitment. The PR is here for feedback on the content and to figure out what we actually want to do with these. See https://staging.mavedb.org/docs/gks-vignettes/index.html for what these vignettes will look like when submitted to GA4GH.


What's here

Four vignettes, each a real implementation walk-through:

  • VRS identity — how every MAVE variant gets a content-addressed VRS 2.0 digest as its canonical ID
  • Cross-score-set harmonization — how the VRS digest collapses independent measurements of the same variant into one record
  • Cat-VRS categorization — how a measured variant can be presented as a category spanning all its molecular-level equivalents (proposal)
  • VA-Spec functional evidence — the full layered stack: study results, functional-impact statements, and pathogenicity statements (production)

The JSON payloads are real exports from the MaveDB API. Large blocks (the 1,332-line GCK pathogenicity statement in particular) are collapsible.

Some of these stories are still aspirational, but all are tractable and in development.


Open question: how visible should these be for MaveDB users?

At minimum we should:

  1. Contribute upstream — these were drafted for the GA4GH GKS Starter Kit (https://github.com/ga4gh/gks-starter-kit) and should be served on their page.

A few options specific to MaveDB consumers:

  1. Link from MaveDB docs — add a "GKS standards" entry to the main doc nav that links to the hosted starter-kit pages once contributed, rather than hosting a copy ourselves.
  2. Keep a local copy — fold these into the main MaveDB docs tree and commit to keeping them in sync when changes come up or are needed.
  3. Remove references — rely exclusively on the GA4GH GKS site for hosting and dissemination.

I lean towards contributing upstream, linking from our docs, and deleting the local copy. The content seems useful to me but the maintenance burden of duplicating them seems unnecessary even if we lose a little discoverability and consistency in documentation style.

If we go with the link out, we can open this PR in the GKS repo and repurpose this one for link outs once accepted.


LMK of any feedback on the content itself:

  • Story sections and the details within
  • Whether any of the payloads could be improved or made more precise
  • If any other details are needed for orientation given these are for an external audience
  • Tool links and tool reuse links

  - Four vignettes covering VRS identity, cross-score-set harmonization,
    Cat-VRS categorization, and VA-Spec functional evidence sharing
  - Standalone MkDocs site under ui/docs-gks-vignettes/ for internal
    preview before upstream contribution to ga4gh/gks-starter-kit
  - use_directory_urls: false to match main docs and fix static serving
  - JSON payload blocks wrapped in collapsible details admonitions;
    large VA-Spec pathogenicity statement collapsed by default, smaller
    payloads expanded
@coveralls

Copy link
Copy Markdown

Coverage Status

coverage: 2.596%. remained the same — docs/bencap/ga4gh-gks-vignettes into release-2026.2.5

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