search

HL7 / fhir-shorthand

FHIR Shorthand
44 stars 8 forks source link

Reorganization #113

Closed markkramerus closed 3 years ago

markkramerus commented 3 years ago

This PR introduces significant changes of many types to the Language Reference. Reviewers will probably be better off reading the entire page, rather than looking at diffs.

markkramerus commented 3 years ago

Chris' comments:

  1. I feel like the note about pages that are informative (Home and Overview) is highlighted too much. It is distracting. I'd suggest toning it down. -- DONE
  2. The section on version numbering seems a little out of place, as the previous sections (Projects, Files, FHIR Version, External IGs) are more about how projects can be organized/defined, whereas Version Numbering is about the FSH Spec itself (i.e., it is more meta than the others). I almost feel like that belongs more in the Home or Overview than in the actual spec. -- DONE Also... we might want to check w/ the FHIR core team about the versioning strategy. I've been hearing rumors that they might (finally) be ready to move toward real semantic versioning! -- PROBABLY TOO LATE FOR THIS BALLOT
  3. When we use italics to optionally indicate a version can be included (e.g., {CodeSystem}|{Version}), the pipe | looks almost like a forward-slash. I'm not sure there is much we can do about it, but we might consider stating that it is a pipe in the following text description whenever that happens? Or just don't worry about it? -- For this reason, I eliminated the italics as indicator of optionality, just used dark orange text as before. The result is that the | and / forward slash for choices can be distinguished. The format for optional syntax is easily changed in the file styles.html if we want to try something different. I've noticed that often items and rules are sorted alphabetically (in tables and in the spec sections). While that is a predictable sort order, I wonder if readers would be better served if we presented things in a more logical order. For example: Profiles, Extensions, Invariants, Mappings, Value Sets, Code Systems, Logical Models, Resources. Or for another example, grouping rules so that VS rules are together, etc. -- I considered that, too, but IMO alphabetical order is a bit more robust and easier to navigate.