Uploaded image for project: 'MedMij Standaarden'
  1. MedMij Standaarden
  2. MM-1292

Stijlen voor implementatiegids vastleggen

    Details

    • Type: Wijzigingsverzoek
    • Status: Gesloten
    • Priority: 3
    • Resolution: Resolved
    • Fix Version/s: 2020.01 - Januari 2021
    • Component/s: None
    • Blokkerend:
      Nee
    • Informatiestandaard:
      Alle
    • Informatiestandaard onderdelen:
      Technisch
    • Impact:
      Geen impact
    • Voorgestelde oplossing:
      Stijlgids vastleggen voor FHIR-elementen, technische artefacten, codes, datatypes, requests. Deze stijlen op de wiki vastleggen in templates en doorvoeren op de algemene en MedMij-FHIR IG.
    • Release notes:
      Hide

      There were no clear style guides for technical documentation. Guidance has been created for common situations and the IG is updated in accordance to these styles.

      Show
      There were no clear style guides for technical documentation. Guidance has been created for common situations and the IG is updated in accordance to these styles.

      Description

      In de verschillende implementatiegidsen worden verschillende stijlen gebruikt om concepten te benadrukken. Te denken valt aan:

      • elementen
      • attributen
      • gebruikte codes
      • operaties, search parameters
      • datatypes
      • requests

      De ene keer worden deze vet gedrukt, de andere keer weer cursief, en de volgende keer als <code>, al dan niet omgeven door enkele of dubbele aanhalingstekens. Het gebruik van stijlen moet gelijkgetrokken worden en vastgelegd.

      Voorstel schrijfwijzes:

      • FHIR-resources, profielen en extensies worden normaal geschreven, bv: "This information shall be conveyed using an Observation resource ...".
      • FHIR-elementen worden altijd met een punt-notatie geschreven, bv ".code" of "Observation.code".
      • FHIR-operations worden altijd met een dollar-teken geschreven.
      • HTTP requests gebruiken de stijlgids die FHIR hanteert:
        • de interactie (GET/PUT/etc) in hoofdletters
        • placeholders die de gebruiker zelf moet invullen met vierkante haken
        • optionele elementen tussen accoulades

      Voorstel lettertypes:

      • FHIR-resources, profielen en extensies worden normaal geschreven, bv: "This information shall be conveyed using an Observation resource ...".
      • FHIR-elementen, -operations en -search parameters worden als "code" geschreven:
        • op wiki via een wiki-template "fhir".
        • in HTML tussen <code>...</code> (inline) of <pre>...</pre>-tags (blok)
        • in Markdown tussen enkele (inline) of drie (blok) backticks
        • elders in een fixed-width font
      • Technische termen zoals protocollen (http, mime-types) worden eveneens als "code" geschreven, maar krijgen op wiki geen eigen template.
      • codes uit een codesysteem worden cursief geschreven:
        • op de wiki via een template "term"
        • in Markdown tussen liggende streepjes
        • elders als cursieve tekst
      • datatypes worden cursief geschreven:
        • op de wiki via een template "datatype"
        • in Markdown tussen liggende streepjes
        • elders als cursieve tekst
      • requests worden als "code" geschreven, doorgaans op een eigen regel:
        • op de wiki met <pre>...</pre>-tags (de karakters in een search URL interfereren met de werking van wiki-templates).
        • in HTML met <pre>...</pre>-tags
        • in Markdown op een eigen regel met een spatie als indent
        • elders op een eigen regel in fixed-width font

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              edelman@nictiz.nl Pieter Edelman
              Reporter:
              edelman@nictiz.nl Pieter Edelman
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Estimations By Role

                  No roles have been estimated yet.