Authoring Best Practice

Jump to bottom Edit New page

Jörn Guy Süß edited this page Jun 12, 2025 · 2 revisions

https://confluence.hl7.org/spaces/FHIR/pages/35718826/Guide+to+Designing+Resources

🔹 1. Clarity and Audience Awareness

Write descriptions with your primary audience in mind—typically implementers, developers, and domain experts.
Use clear, concise language and avoid unnecessary jargon.
Provide context for why a profile, extension, or resource is included and how it should be used.

🔹 2. Consistency Across the IG

Maintain consistent terminology, formatting, and structure throughout the guide.
Use templates or follow established patterns from other well-regarded IGs to ensure uniformity [1](https://build.fhir.org/ig/FHIR/ig-guidance/best-practice.html).

🔹 3. Use of Markdown and Narrative

Leverage Markdown for formatting (headings, lists, links) to improve readability.
Include narrative sections that explain the purpose and usage of profiles, extensions, and value sets in plain language.

🔹 4. Descriptive Metadata

Populate the description, purpose, and usage fields in FHIR resources like StructureDefinition, ValueSet, and CodeSystem with meaningful content.
These fields should explain the intent, scope, and any constraints or assumptions.

🔹 5. Examples and Use Cases

Provide real-world examples and use cases to illustrate how the IG should be applied.
Include example resources with narrative to help implementers understand the expected structure and content.

🔹 6. Validation and Review

Use the FHIR IG Publisher to validate your IG and ensure it renders correctly.
Peer review by domain experts and potential implementers is highly recommended.

🔹 7. Referencing Existing Standards

Where possible, align with existing profiles (e.g., US Core, AU Base) to promote interoperability and reduce duplication [2](https://www.cdc.gov/nchs/nvss/modernization/pdf/fhir-implimentation-guidance-checklist.pdf).

You can find a detailed guide on best practices for IG creation here: [FHIR IG Best Practices](https://build.fhir.org/ig/FHIR/ig-guidance/best-practice.html) [1](https://build.fhir.org/ig/FHIR/ig-guidance/best-practice.html).