Difference between revisions of "Editing and Style Guide"
(Initial Draft) |
Calvin Beebe (talk | contribs) m |
||
(3 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== |
− | + | Wiki formatting should be limited to: | |
− | + | * <nowiki>'''Bold'''</nowiki> for '''Bold text''' | |
− | + | * <nowiki>*</nowiki> for bulleted lists | |
− | + | * <nowiki>[[Page Name#Section_Heading]]</nowiki> - Links to other parts of this guide (page name contains spaces; for section headings, convert spaces to underscores) | |
− | + | * <nowiki>{{ext|processable/localfile.xsd}}</nowiki> - Links to files released as part of the CDA sepcification (see [[#External_References ]]) | |
− | + | * Tables and Examples formatted as below | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===Tables=== | ===Tables=== | ||
All tables are formatted identically. The <nowiki>{{AUTOTABLENUM}}</nowiki> 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. | All tables are formatted identically. The <nowiki>{{AUTOTABLENUM}}</nowiki> 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. | ||
Line 46: | Line 43: | ||
... | ... | ||
<componentOf></nowiki></pre> | <componentOf></nowiki></pre> | ||
+ | |||
+ | |||
+ | ==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. | ||
+ | |||
+ | ==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, | ||
+ | |||
+ | <nowiki> | ||
+ | =CDA Overview= becomes --> 1. CDA Overview | ||
+ | |||
+ | while | ||
+ | |||
+ | ====performer==== becomes --> 4.2.2.10 Performer</nowiki> | ||
==External References== | ==External References== |
Latest revision as of 14:10, 24 July 2015
Contents
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:
<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.