Difference between revisions of "Editing and Style Guide"

From HL7 Publishing Wiki
Jump to navigation Jump to search
(Add general formatting tips)
m
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
==Updating Content==
 +
When changing content, add the following notations in the Summary field:
 +
* %N% - Normative or modeling changes
 +
* %I% - Informative or clarification changes
 +
*  If the change is minor or typo check the [] This is a minor edit, below the summary field.
  
 
==Formatting==
 
==Formatting==

Latest revision as of 14:10, 24 July 2015

1 Updating Content

When changing content, add the following notations in the Summary field:

  • %N% - Normative or modeling changes
  • %I% - Informative or clarification changes
  • If the change is minor or typo check the [] This is a minor edit, below the summary field.

2 Formatting

Wiki formatting should be limited to:

  • '''Bold''' for Bold text
  • * for bulleted lists
  • [[Page Name#Section_Heading]] - Links to other parts of this guide (page name contains spaces; for section headings, convert spaces to underscores)
  • {{ext|processable/localfile.xsd}} - Links to files released as part of the CDA sepcification (see #External_References )
  • Tables and Examples formatted as below

2.1 Tables

All tables are formatted identically. The {{AUTOTABLENUM}} will look like just an X or # on the wiki, but will be used to identify all tables and automatically generate a new number for each table. Remember to never refer to a particular table or example by number because it may change in the final guide.

{| class='wikitable'
|+Table {{AUTOTABLENUM}}: Title (this is the table caption)
!Header Cell!!Header Cell
|-
|Data Cell||Data Cell
|-
|Data Cell||Data Cell
|}

2.2 Examples

Examples are wrapped in <nowiki> ... </nowiki> tags. Start the first <nowiki> tag with a space to create the 'Example' box. The {{AUTOEXAMPLENUM}} will look like just an X or # on the wiki, but will be used to identify all examples and automatically generate a new number for each table. Remember to never refer to a particular table or example by number because it may change in the final guide.

For example, the following box:

Example X
<ClinicalDocument>
  ... 
  <componentOf>

Is created from the following markup:

<div align="center">Example {{AUTOEXAMPLENUM}}</div>
 <nowiki>
<ClinicalDocument>
  ... 
  <componentOf></nowiki>


3 Chapters (Pages)

If you add or remove entire chapters, be sure to update the front table-of-contents page as well as all other top-level pages with the correct links to all sections. This will keep numbering consistent on every page.

4 Section Titles

If you change or remove a section title, be sure to search the entire guide for bookmark links to the old title. Links are based on the title text, not the section number, so any change in the name of a section will break existing bookmarked links

Section titles are created from the original standard simply by adding the number of outline levels as = marks. So,

=CDA Overview=    becomes  -->   1. CDA Overview

while

====performer==== becomes  -->   4.2.2.10 Performer

5 External References

For the time being, any out-of-page references to HL7 package content use the

{{ext|path (no leading /)|name}} 

template. This allows us to easily re-locate the wiki or point to a different host if needed. Links to sites like LOINC or SNOMED continue to use the default

[[URL Link Name]]

format.

MediaWiki automatically adds links to RFC specifications, like RFC 2046 so that's neat.