diff --git a/README.md b/README.md index c8eb476c5..f70ba4513 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,50 @@ # ncpi-fhir-ig-2 Welcome to NCPI FHIR IG 2. The goal for this repository is to relaunch the IG project with a clearer focus, an explicit style guide using the current tools including Sushi v3. -This repository is currently under development. Feel free to [take a look](https://torstees.github.io/ncpi-fhir-ig-2/) at the working version. +# Contributing Quick Updates +The contribution content I wrote back during the initial start for IG v2 is somewhat outdated, but I don't have time to correct it for this gathering. So, here are some key points to consider if you are up for contributing: + +## Module Content Requirements +### FSH Artifacts +#### Profiles, Logical Model and Extensions +Non-example content specific to a single module should be defined within a single file inside the directory, input/fsh/modules. This file should be named clearly after the module name (such as participant.fsh for participant specific module content.) Content that should be contained within this file should be all terminologies, extensions and profiles that are specific to the module only. All modules should have a complete set of Logical Models defined the reflects the SharedDataModel representation upon which the mappings and profile are based. + +For extensions and terminologies that directly relate to more than one module should be defined elsewhere (such as input/fsh/extensions, input/fsh/terminologies, etc). + +#### Non-Profile Multi-Module Content +For terminologies, extensions and other content that is necessary for more than one module, they should be defined inside the corresponding directory (input/fsh/terminologies, etc). For filenames, it should be clear from the filename what is contained inside. + +For tightly coupled entities, such as a ValueSet which includes only terms from a given CodeSystem, the ValueSet should be defined alongside the parent CodeSystem. However, if the ValueSet is comprised of codes from multiple CodeSystems and isn't defined for a singular purpose (such as binding to a specific field within a profile), that ValueSet should be defined inside the terminology directory within its own file. + +#### Examples +Defining examples for your IG components will eliminate warnings from your QA log, but also allow you to catch tricky issues with your profiles and extensions. It is therefore, expected that all Profiles and Extensions in active use be accompanied by an example resource. + +### Markdown Content + +#### Technical Documentation for Profiles and Relationships - Artifact Intro and Notes +For intro and notes content that will be merged into the relevant artifact page, the publisher application itself is very specific: The filename should match the resulting HTML file in Humpback notation minus the extension followed by either "-intro.md" or "-notes.md". The material inside -intro.md files will appear *before* the differential table. Material inside -note.md files will appear afterward inside the header, *Notes". These files will be written into the directory, input/pagecontent. + +> To determine the correct filename corresponding to the artifact of interest, please see the file, fsh-generated/includes/fsh-link-references.md where you can find the resulting HTML filename for each FSH based artifact. + +For each profile, there should always be a matching -info file that contains the following information: +* Profile Overview indicating the role the profile is expected to perform +* Mapping table showing how properties from the logical model(s) map into the specified profile +* Relationships between the current profile and other resources and profiles + +The -notes.md file is optional and should be used to add clarification for unusual cases or other details that should be called out that don't naturally fit within the typical use cases. + +#### Example Overview +Each module should have at least a single example page as part of the release. This should, at the very least, link each of the associated example profiles with an explanation of how they fit together if the example spans multiple profiles. To provide context within the example page itself, you can provide -info.md and -notes.md pages similarly to profiles, extensions, etc. + +#### Module Overview +High-level documentation written for researchers and non-implementers about the module's purpose should be provided inside an aptly named file, prefixed with module_ inside the input/pagecontent directory. + +#### (TBD) Use-Case Overview +Overview of each of the use cases for which the module was was designed to address. + +These markdown files will be defined inside the input/pagecontent directory with names that begin with *use-case-*. + +### Linking Markdown into the Menu +Content inside properly formed -info.md and -notes.md files will be merged into the appropriate pages built around the various FSH artifacts. The other .md files inside input/pagecontent will be compiled into .html but must be manually referenced either by link markup from other pages, or directly to the menu via the root file, sushi-config.yaml. + +We provide a top level menu entry for Modules, Use Case Guides and Examples and authors should link their top level pages accordingly. Profiles will automatically be added to the the Artifacts links. \ No newline at end of file diff --git a/input/fsh/Example-ResearchStudy-BH-CMG.fsh b/input/fsh/examples/ResearchStudy-BH-CMG.fsh similarity index 100% rename from input/fsh/Example-ResearchStudy-BH-CMG.fsh rename to input/fsh/examples/ResearchStudy-BH-CMG.fsh diff --git a/input/fsh/Example-ResearchStudy-CBTN.fsh b/input/fsh/examples/ResearchStudy-CBTN.fsh similarity index 100% rename from input/fsh/Example-ResearchStudy-CBTN.fsh rename to input/fsh/examples/ResearchStudy-CBTN.fsh diff --git a/input/fsh/Extension-Label.fsh b/input/fsh/extensions/Label.fsh similarity index 100% rename from input/fsh/Extension-Label.fsh rename to input/fsh/extensions/Label.fsh diff --git a/input/fsh/Extension-research-web-link.fsh b/input/fsh/extensions/ResearchWebLink.fsh similarity index 100% rename from input/fsh/Extension-research-web-link.fsh rename to input/fsh/extensions/ResearchWebLink.fsh diff --git a/input/fsh/Profile-research-access-policy.fsh b/input/fsh/modules/research-accesss-policy.fsh similarity index 100% rename from input/fsh/Profile-research-access-policy.fsh rename to input/fsh/modules/research-accesss-policy.fsh diff --git a/input/fsh/Profile-research-collection.fsh b/input/fsh/modules/research-collection.fsh similarity index 100% rename from input/fsh/Profile-research-collection.fsh rename to input/fsh/modules/research-collection.fsh diff --git a/input/fsh/Profile-research-study-group.fsh b/input/fsh/modules/research-study-group.fsh similarity index 100% rename from input/fsh/Profile-research-study-group.fsh rename to input/fsh/modules/research-study-group.fsh diff --git a/input/fsh/Profile-research-study-subject.fsh b/input/fsh/modules/research-study-subject.fsh similarity index 100% rename from input/fsh/Profile-research-study-subject.fsh rename to input/fsh/modules/research-study-subject.fsh diff --git a/input/fsh/Profile-research-study.fsh b/input/fsh/modules/research-study.fsh similarity index 100% rename from input/fsh/Profile-research-study.fsh rename to input/fsh/modules/research-study.fsh diff --git a/input/fsh/CodeSystem-ncpi.fsh b/input/fsh/terminologies/ncpi.fsh similarity index 100% rename from input/fsh/CodeSystem-ncpi.fsh rename to input/fsh/terminologies/ncpi.fsh diff --git a/input/pagecontent/downloads.md b/input/pagecontent/downloads.md new file mode 100755 index 000000000..817a9dd26 --- /dev/null +++ b/input/pagecontent/downloads.md @@ -0,0 +1,21 @@ +### Downloads +Download the IG and other content + +Possible TODO: Incorporate an archival system so we can provide older versions at some point + +#### Full IG Download +[Full IG](full-ig.zip) + +#### Definitions +* [Definitions JSON](definitions.json.zip) +* [Definitions TTL](definitions.ttl.zip) +* [Definitions XML](definitions.xml.zip) + +#### Examples +* [Examples JSON](examples.json.zip) +* [Examples TTL](examples.ttl.zip) +* [Examples XML](examples.xml.zip) + +#### Expansions +* [Expansions JSON](expansions.json.zip) +* [Expansions XML](expansions.xml.zip) diff --git a/input/pagecontent/fhir_version.md b/input/pagecontent/fhir_version.md new file mode 100644 index 000000000..1d223bed4 --- /dev/null +++ b/input/pagecontent/fhir_version.md @@ -0,0 +1 @@ +At this time we are focussing the majority of our efforts on mapping the research study components to R4, with the release of R5 in February 2023 we are including them in this iteration but on an experimental basis. Please see the research study documentation for in-depth mappings on a R5 version as well as a R4 version and the necessary extensions needed to ensure interoperability. We are not recommending or mandating an upgrade of your local FHIR instance at this point, if this changes we will communicate the next steps and rationale to all stakeholders. diff --git a/sushi-config.yaml b/sushi-config.yaml index aee5fe85d..dcd3f4075 100644 --- a/sushi-config.yaml +++ b/sushi-config.yaml @@ -112,7 +112,6 @@ menu: Code Systems: artifacts.html#terminology-code-systems Value Sets: artifacts.html#terminology-value-sets Extensions: artifacts.html#structures-extension-definitions - Data Types: artifacts.html#structures-data-type-profiles Support: FHIR Versions: fhir_version.html FHIR Spec: http://hl7.org/fhir/R4/index.html