Dataset Producer Documentation Guidance

[larrybabb]

Submitter Name

Larry Babb

Submitter Affiliation

Broad Institute/ClinGen

Project Details

The real value of GKS is in having access to datasets that are structured using VRS, Cat-VRS and VA-Spec. However, the producers of that data could benefit from knowing what minimal level of detail should belong in their documentation for specific datasets vs where the common docs would pick up.

Ultimately we will want the GKS docs to have a "reference" to implementer sites for specific dataset docs, but this is more about starting some baseline guidance on how and what to provide in terms of content for implementers. Some areas that need support are: Extensions, versioning, understanding how the common GKS docs are organized so that links are reliable, etc...

Required Maintainer(s) Attendance

No response

Required Skills

technical writing, organizational skills, understanding and experience with what makes good API/schema documentation

[egchristensen]

I wonder if any of the documentation and metadata recommendations from Elixir's Research Data Management toolkit might be relevant to this issue?

[melissacline]

@egchristensen Is there anything in particular that you're thinking of under that link?

[egchristensen]

I was thinking some of the bullets on metadata in the "solutions" section (about half-way through) might be useful when considering how to structure descriptions of resources and documentation for/from implementations. I doubt we'll be making a full-fledged metadata repository here, but it might be helpful to see what sorts of metadata standards we'd like to employ at GKS. Especially as we start to discuss descriptions of code through various stages of the GKS maturity model and as developed/implemented at various sites.

For example:

• Do we want to recommend the generation of DOIs for each version of documentation or just one DOI that links to the most recent release?
• How will a user know if the documentation about a certain GKS object is complete and up to date? Is there a way to automatically check whether the code for a specific object has been changed more recently than the documentation for that object?
• What differences (if any) exist between the GKS standard and any workarounds put in place by an implementer?
• Do we even have such metadata at our fingertips?