search

clingen-data-model / allele

Documentation for data model of ClinGen
10 stars 2 forks source link

change styling of context to match what @larrybabb had done with other pages #111

Closed bpow closed 9 years ago

bpow commented 9 years ago

Just to put this out there for discussion, this would produce output similar to what @larrybabb has done for the other resource models, but using the 'context' data in the yaml header.

larrybabb commented 9 years ago

I really like it. Very nice work.

The only minor comment I have is the removal of the fully qualified attribute name. I understand the reasoning. "Why so much redundancy? Since the attributes are listed on the same page as the Resource, then there is really no reason to prefix every attribute with the Resource name."
The reason I had done this was to follow the FHIR documentation approach. I believe they have a couple justifications for it. One, when you scroll down a page and potentially loose the context of the Resource you are on, it is possible that some of the unqualified attributes may be confused with attributes from other Resources (particularly as the model grows). Two, FHIR tends to not only include documentation on each attribute but also on each relationship and the root resource itself. Three, the FHIR doc site puts the attributes on a separate tab from the main resource and has the potential to provide lists that involve attributes from multiple Resources, so it provides a mechanism sorting and namespace safety.

Here's an clip from the Observation Formal Definitions. I circled the first detail description which is of the root Resource itself.

In my opinion, we can cut out the fully qualified name, however, I think the less we deviate from the FHIR specification the less we have to think and maintain rules for on our own.

image

bpow commented 9 years ago

I actually just took the fully-qualified name out of the yaml structure in the page, but it currently renders back into the html by taking the info from elsewhere in the page header (for now). That keeps redundancy out of the "primary source" while allowing it to be present where it may be useful visually.

Having a list of definitions for the resource itself would just require adding material to the page header as well, from which it can be pulled.

I'll go ahead and merge this. It will be easy enough to back it out later if we come up with something better.

tnavatar commented 9 years ago

Definitely go ahead and merge. I'm doing my work in a separate branch anyway. I'm perfectly happy working with more structured data now, even if we shift to an Avro representation later.

On May 15, 2015, at 9:48 AM, Bradford Powell notifications@github.com wrote:

I actually just took the fully-qualified name out of the yaml structure in the page, but it currently renders back into the html by taking the info from elsewhere in the page header (for now). That keeps redundancy out of the "primary source" while allowing it to be present where it may be useful visually.

Having a list of definitions for the resource itself would just require adding material to the page header as well, from which it can be pulled.

I'll go ahead and merge this. It will be easy enough to back it out later if we come up with something better.

— Reply to this email directly or view it on GitHub.