Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Model Documentation Updates #197

Open
bessleroy opened this issue Jun 28, 2023 · 1 comment
Open

Model Documentation Updates #197

bessleroy opened this issue Jun 28, 2023 · 1 comment

Comments

@bessleroy
Copy link

bessleroy commented Jun 28, 2023

  1. Update integer description: should we consider providing fuller descriptions? These come directly from LinkML.
  2. It would be helpful to put the full model mermaid diagram on the main landing page. Although it is big, it could be helpful for users to orient themselves.
  3. Consider adding descriptions of classes, slots, enumerations, and types. If we aren't using subsets should that be removed?
  4. Add description on how to interpret "Cardinality and Range".
  5. Consider fleshing out the ARS description on the landing page.
  6. Is order important or helpful to implementers vs. just alphabetical order on landing page (e.g., class)
@ASL-rmarshall
Copy link
Collaborator

ASL-rmarshall commented Jul 21, 2023

  1. As mentioned - currently all of the (data) types used in the model are imported from the LinkML definitions, so the descriptions are as defined in LinkML. It would be possible to define our own data types (which can have an indication that they're based on LinkML data types and/or other definitions - e.g. NCI), but this might need to be more of a strategic decision.
  2. I've added the schema diagram and have configured this and all other class diagrams to have pan/zoom controls.
  3. I've copy/pasted brief definitions of each of the subsections from the LinkML documentation, and have added links to the relevant sections of the LinkML documentation "for more information". The Subsets section can be removed if it's unused. However, I've been considering using subsets to "categorize" model components and analysis vs output.
  4. I added an asterisk next to "Cardinality" in the column header and a footnote with a link to the LinkML documentation definitions of the cardinalities. Does range need separate explanation?
  5. We'd need to decide what to include. The text comes directly from the "description" attribute of the schema so we could either update that or it would be feasible to add a separate page with additional information. I guess we'd also need to decide what goes here, what goes in the GitHub readme and what goes in the user guide, and whether we want to repeat information in the various places.
  6. Order is not particularly important (I think). I have changed the ordering to reflect the order in which the classes/slots are defined in the model, and have updated the model to put things in a vaguely logical order.

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

No branches or pull requests

2 participants