search

airr-community / airr-standards

AIRR Community Data Standards
https://docs.airr-community.org
Creative Commons Attribution 4.0 International
35 stars 23 forks source link

Redundant section in Docs #730

Open bcorrie opened 8 months ago

bcorrie commented 8 months ago

In the AIRR Standards section, we have:

Under Data Model, we have:

AIRR Standards -> V(D)J Sequence Representation just links to AIRR Standards -> Data Model -> Rearrangement Schema AIRR Standards -> Metadata Representation just links to AIRR Standards -> Data Model -> Repertoire Schema

This is confusing and I think a left over from past days when that was all there was???

I would suggest removing the menu items: AIRR Standards -> V(D)J Sequence Representation AIRR Standards -> Metadata Representation

javh commented 8 months ago

It's deliberate. The intent being to make the two primary use cases easier to find. I think Data Model is too high up the tree.

Though, we need to rework "Getting Started" so we can do this better via that page.

bcorrie commented 8 months ago

It seems quite confusing to me - maybe partially because the names are so different, maybe partially because I am so past just being about Rearrangements 8-). I suppose since the other schemas are still "Experimental" this makes sense but for v2.0 I would hope that we would be past that???

One confusing thing is you click on Metadata and it takes you to Repertoire and you click on V(D)J Sequence Representation and it takes you to Rearrangement. The links between the two wordings are not obvious...

If you want you can close this and create a different issue as you see fit, although maybe it makes sense to keep it open for v2.0 release?

schristley commented 8 months ago

I agree that the organization seems somewhat odd. The Data Model section is meant to introduce all of the objects and their relationship to each other, I think it does a somewhat decent job there.

One thing I've always found odd is that if you go under MiAIRR, it doesn't really tie into any of the appropriate data standards. One idea is that Metadata and V(D)J Sequence go under MiAIRR.

Another idea as Jason suggests is to fill out Getting Started so that it does a better job of explaining the organization of the website and where to find things.

bussec commented 6 months ago

From the call: Discuss again in January, potential strategy for v2.0 might be to complete the Docs first in terms of content and then have a look at a meaningful and consistent structure for the individual sections.

javh commented 5 months ago

From the call:

ustervbo commented 5 months ago

I agree with Brian and Scott; the organization is odd, and I think that the sections V(D)J Sequence Representation and Metadata Representation should only be subsections somewhere.

We can (and probably should) add more information to Getting Started, but I don't think it will solve the confusion in the structure and the redundant entries.

Reading through the documentation front to back, I have found other oddities:

I perceive the Study Reporting (MiAIRR) section as merely providing an overview. Details are left to the further subsections, each of which serves as a reference. The subsection MiAIRR-to-NCBI Specification is out of place and is probably better off in Data Submission and Query alone.

The section Metadata Annotation Guidelines in Study Reporting (MiAIRR) doesn't tie to anything and seems to come out of left field. Its purpose is very confusing, but maybe, based on the coincidence of 'Metadata', it thematically goes with Metadata Representation.

The TOC entry Study Reporting (MiAIRR) is probably better as Introduction to MiAIRR, because that is what it is - it is not about how to report a study. The section can keep MiAIRR Data Elements as a subsection. I think it should be the only subsection. Everything else should go someplace else.

Should the TOC entry Data Model be named Data Representations? At least then it matches the heading in the document it points to. Also, Data Model is only a subsection in that document. Irrespective, the TOC level can be the same as it is, and subsections can also stay. The Annotation Guidelines could go into this TOC element too.

The connection between the Data Model and the primary schema objects of the AIRR Data Model is missing. The first four schema objects are easy to place; the rest require some guesswork.

javh commented 5 months ago

From the call:

bcorrie commented 4 months ago

Changed to AIRR 2.0, since this is not ADC specific.