Exchange+Documentation+Guidelines

toc =Nationwide Health Information Network Exchange Documentation Guidelines=

DRAFT STATUS

The purpose of this page is to provide potential authors with general expectations regarding Nationwide Health Information Network Exchange documents. A document will, in the very near future, be only one (but a key) component of the overall "toolkit" that is provided to end-users of Nationwide Health Information Network Exchange specifications. See the NIEM IEPD page on this site for more information.

Process

 * 1) Use a contemporary version of Microsoft Word or OpenOffice to create documents using the Nationwide Health Information Network Exchange Word template. 
 * 2) Use the most recent version of existing specifications as a model for the look and feel and appropriate use of styles.
 * 3) Add references for all underlying standards, with a URL link to the governing body or document. If possible, save a copy of the referenced documents locally and post to this Wiki. Be certain to honor any copyright or other legal restrictions imposed by the referenced document's owner.
 * 4) Ensure the ONC S&I Framework Compliance Testing Team has had a chance to provide feedback on the testability of the content.
 * 5) Involve other testing teams, such as ones internal to your organization, and ideally all other stakeholders, in writing and/or reviewing your content. A broad group of stakeholders should be involved early and heavily in the process to reduce the risk of problems and subsequent rework.
 * 6) Before publishing an updated version of a document, please add a very succinct, but complete, list of substantive changes to the document revision history. Editorial changes (formatting, wordsmithing, white space changes, and similar) should be omitted from the change log unless they change the meaning of the document.
 * 7) Perform the QA checklist (below).
 * 8) Post the PDF version of the document for general review, and provide the .DOC or .DOCX version to the editorial team.
 * 9) If you are writing sections of a document, rather than an entire document, please use no formatting or styles, and include detailed integration instructions to the person that will be incorporating your text into the overall document.
 * 10) If you find a better way to do something, please share your idea(s) with the team for consideration! We want to improve each iteration.

Policy Issues

 * 1) The Nationwide Health Information Network Exchange Specification Factory does not make policy. But frequently technical specifications for the Nationwide Health Information Network Exchange have specific topics with an intersection between technology and policy. This can take several forms. Policy can drive technology decisions. Or policy can be absent or unclear. In either case, it is important to implement traceability between a technical specification requirement, and any existing or absent (but likely needed) policy related to the issue.
 * 2) Often the technical specification cannot be completed (in a testable and implementable manner) without a precise statement. And some of those precise statements have policy implications.
 * 3) As an author you should consider policy implications in your content, and clearly articulate what policy intersections and implications exist.
 * 4) If your content has an associated policy, you should reference the policy statement.
 * 5) If you find no existing policy, and you need to precisely indicate something in your content that would have the effect of setting policy, you should a) discuss this issue broadly with at least the entire Nationwide Health Information Network Exchange Spec factory and the ONC, and b) unless guided otherwise, create a written list of policy issues that should be addressed at the Nationwide Health Information Network Exchange governance level, and c) make a statement in your content similar to the following "In the absence of Nationwide Health Information Network Exchange policy to the contrary ....". For example, when specifying the maximum x.509 certificate revocation interval, you may want to write "In the absence of Nationwide Health Information Network Exchange policy to the contrary, Nationwide Health Information Network Exchange gateway implementers MUST check for x.509 certification revocation status at least once per hour OR the first time a exchange occurs if more than one hour has elapsed between now and the last certificate revocation status check."

Editorial Guidelines

 * 1) Do not add or change styles.
 * 2) Note that source code and XML content should be inside a specific style, and should be in a mono-spaced font.
 * 3) Add line numbers to the left margin of the document.
 * 4) Use a Table of Contents in your document.
 * 5) Ensure headers in your document have the proper styles to display properly indented in the Table of Contents.
 * 6) All references should be as precise as possible, pointing not only to the document, but the organization, the version and date of the document, and any applicable sections inside the document.
 * 7) Use upper case letters for all "significant" words in headers. Minor words (of, the, if, or, and, etc...) should be in all lower case unless they are the first word in the header.
 * 8) All sections should use automatic section numbers (like 2.3.1).
 * 9) Clearly mark normative sections of your content with the text "Normative".
 * 10) Use MUST, CAN, SHOULD, MAY, etc. precisely in your normative content sections, as per IETF recommendations found here.
 * 11) Use a syntax coloring editor as the source for XML and source code snippets (such as NotePad++) and past the examples into the document with syntax highlighting preserved.

Quality Assurance
Before posting a document please follow the below pre-flight checklist.
 * 1) Check each reference URL to ensure the document is available.
 * 2) Update the Table of Contents.
 * 3) Create a PDF version of the document and ensure it renders correctly and has reasonable page breaks, margins, and white space.
 * 4) To ensure your document change history is rigorously complete, please use you word processor's "document comparison" feature to carefully cross check your change l
 * 5) Spell check.
 * 6) Copy and paste any XML or source code snippets into a plain text editor such as NotePad++ to ensure it pastes properly. Watch for problems with quotes in particular to ensure your word processor didn't translate them improperly.
 * 7) Ensure XML or source code snippets are validated for syntax, and if applicable, parse and/or compile properly. For XML, if the example is a complete document, ensure it is well-formed and valid.
 * 8) Ensure that the auto spell checker "red squiggly underlines" don't appear in the published versions of the document, either in text or in XML or source code snippets.
 * 9) Try to maximize the testability of the normative sections of your content. Ideally, the normative sections are testable in an automated manner (as opposed to requiring human judgment).

Specifications

 * 1) Each specification and profile should clearly specify all exceptions that should be handled, and the expectations of the handlers.
 * 2) Each specification and profile should include a security considerations section.
 * 3) Each specification and profile should include a logging considerations section.
 * 4) Each specification and profile should include a policy considerations section.

Tips

 * 1) Please be as rigorous and as precise as possible with your content! English is often subject to interpretation leading to interoperability problems. Keep in mind that some readers, while being technically proficient, don't have the same context you, as the author and a subject matter expert, have.
 * 2) Key aspects of your text probably should have a section tagged a "normative". This content should be complete, implementation neutral, technology neutral, and as generic as possible. Avoid examples even in individual fields or attributes and instead use patterns and schemas to describe them.
 * 3) A very common mistake is to intertwine precise, but "cold", normative text with advice, guidance, and examples for readers. Please keep this "warm" text in the specification; it is enormously valuable! But, please put it in a subsequent paragraph, or section, clearly marked as "non-normative".
 * 4) Directly quote short relevant sections of reference documents if permitted by the reference document. Generally, most reference documents specifically permit the use of short quotes with proper attribution.

Maintainers: This page was initially written by Eric Heflin, and is maintained by the Nationwide Health Information Network Exchange Workgroup Chairs.