Documentation and Testing Meeting 2010-09-15

Notes from Documentation and Testing WG Meeting
Date: September 15, 2010
Time: 2:00pm-3:00pm
Attendees: Janet Campbell, John Moehrke, Nageshwara Bashyam, Karen Witting, Parag More, Andy Oram, Will Ross, David Tao, Douglas Pratt, Arien Malec, Caitlin Ryan
Actions for This Week

#	Date	Action	Status	Owner	Due Date
46	2010-09-15	Look at Deployment Models document.	Open	WG members	2010-09-22
47	2010-09-15	Sign up for the Google Group so you are not left out of emails.	Open	WG members	2010-09-22
48	2010-09-15	Edit Deployment Models document.	Open	David Tao	2010-09-22
49	2010-09-15	Send document URLS out via the Google groups, at the request of Andy Oram.	Open	Janet Campbell	2010-09-22
50	2010-09-15	Draft “NHIN Direct Specifications” document and schedule document focus meeting.	Open	Arien Malec	2010-09-22
51	2010-09-15	Look over API documents.	Open	Andy Oram	2010-09-22
52	2010-09-15	Point Andy Oram in the right direction for API documents.	Open	Arien Malec	2010-09-22
53	2010-09-15	Reach out to Mr. Palmer about his work on a document similar to the Email Client Configuration Guide.	Open	Dragon Bashyam	2010-09-22
54	2010-09-15	Schedule XD* focus meeting for next Thursday morning.	Open	Arien Malec	2010-09-22
55	2010-09-15	Work on XD* document over the next week.		Arien Malec, David Tao	2010-09-22
56	2010-09-15	Begin drafting a new document with the objective: documenting for how someone can take existing implementation reference and translate it to be able to send/receive NHIN Direct messages.	Open	Karen Witting, David Tao, Janet Campbell	2010-09-22
57	2010-09-15	Rename the XDD document “XD* for Direct.”	Open	WG	2010-09-22
58	2010-09-15	Map out documentation so readers know the pattern in which they should read.	Open	WG, Team	2010-09-22
59	2010-09-15	Ask Paul Tuten for FAQs list to be put on the wiki.	Open	Janet Campbell	2010-09-22
60	2010-09-15	Start tracking the status of documents in the documentation table.	Open	Janet Campbell	2010-09-22
61	2010-09-15	Create a Master Glossary for the wiki, for glossaries within other documents to link to.	Open	WG? Team?	2010-09-22
62	2010-09-15	Draft high-level Testing Guide.	Open	John Moehrke	2010-09-22
63	2010-09-15	Edit high-level Testing Guide.	Open	Arien Malec	2010-09-22

Actions from Last Week

#	Date	Action	Status	Owner	Due Date
34	9/8/10	Add Overview comments to the wiki. (LINK: NHIN Direct Overview Call for Consensus)	Closed	Janet Campbell	9/9/10
35	9/8/10	Edit final draft of NHIN Direct Overview.	Open	Original editors + Karen Witting and Noam Arzt	9/14/10
36	9/8/10	Schedule NHIN Direct Overview meeting for this coming week.	Open	Janet Campbell	9/10/10
37	9/8/10	Complete S/MIME Spec with edits and additional threat model.	Open	Arien Malec Sean Nolan	9/14/10 (draft by 9/9/10)
38	9/8/10	Reschedule XDD meeting for 2:00-3:00 or before 12:30 because Karen, John, and Vassil will be on another call.	Open	Arien Malec	9/9/10
39	9/8/10	Sign up on the wiki or through Dragon to assist with the NHIN Direct Security Overview. Group will meet Monday (09/13/10).	Open	Interested WG members	9/13/10
40	9/8/10	Start putting together rough draft of Implementation Geographies FAQ list.	Open	Janet Campbell	9/14/10
41	9/8/10	Continue work on Deployment Model	Open	John Moehrke	9/14/10
42	9/8/10	Help shepherd the process of interviewing developers to enable quality documentation of code.	Open	Andy Oram	Ongoing
43	9/8/10	Assist with documentation of Java code.	Open	Andy Oram	Ongoing
44	9/8/10	Join Reference Implementation calls to serve as liaison between WGs.	Open	Andy Oram (ONC team will facilitate)	9/9/10
45	9/8/10	Set up a Google group mailing list for the Doc and Testing WG.	Open	ONC Team	9/9/10

Notes:
Janet Campbell
· Proposed going down the table of contents [LINK: Documentation Priorities] as the agenda for the meeting.
John Moehrke
NHIN Direct Deployment Models
· Spent time today fixing up the items he had already gotten feedback on, and adding details on some of the other models.
· Hasn’t done the NHIN Direct/NHIN Exchange deployment model; will have to be renamed due to discussions about the XDD spec.
· Encouraged others to look at prior conversations to understand the pros and cons and general overview.
· He attempted to clearly demonstrate that any sender should be able to hook up to any receiver, because they are all speaking a common NHIN Direct protocol in between.
David Tao
· -->Will take a look at the Deployment Models document.
John Moehrke
· Admitted the Deployment Model document is from his perspective and is still very sparse.
Janet Campbell
· -->Suggested all WG members look over the Deployment Models document to familiarize themselves with it and give feedback on the general direction of the document.
· Has noticed a pattern that one person will write a document, and a core round of editors make the initial edits, but then when the document enters larger rounds of editing, big things are still being changed at a time when there should only be small changes made.
Andy Oram
-->Requested that someone to send out URLs to the documents mentioned during the meeting.
Janet Campbell
-->Will send out links via the Documentation and Testing WG Google Group.
Caitlin Ryan
· Explained how to join Google Group from the WG wiki page.
John Moehrke
· Suggested WG add a priority number for the Deployment Models.
Janet Campbell
· Voted to put Deployment Models as a Priority Two document.
· Asked if anyone disagreed strongly.
<All agreed.>
John Moehrke
· Agreed that the document would be very helpful, and should be Priority Two.
Janet Campbell
· Thinks the document is very helpful because people are starting to get into implementations and depending on the deployment model they are using, they can draw comparisons, i.e. “my HISP is similar to Case A, therefore…”
John Moehrke
Content Security for Simple Health Transport Specification
· Security and Trust WG discussed in detail at their last meeting.
o Decided a lot of content is not specific to security, but is important to NHIN Direct overall.
o Promoted the document to the Documentation and Testing WG for further work.
o Suggested the document become part of a single document that represents all of the specifications, not individual specifications for Content, Addressing, etc.
Janet Campbell
· Agreed that merging the document made the most sense.
· Asked if there is a good understanding of what that document does not have but needs from the Documentation and Testing WG.
John Moehrke
· Proposed that Arien might have a better idea of what is still missing.
· Believes there is nothing on the spec for an address or for content and XDM encoding, so those would need to be folded in.
Arien Malec
(Joined.)

Janet Campbell
· Agreed with plan.
o Because the scope is already creeping, suggested the WG be specific and call it “NHIN Direct Specifications” and merge all of the specs together.
o Asked for other items to add to the document.
Arien Malec
· Elected to add:
o Addressing specification
o Content specification
o Consensus proposal
o But to leave out the XDD specification.

John Moehrke
· Agreed that XDD is a particular deployment and should be kept separate.

Janet Campbell
· Asked what the next steps are for this document.
· Arien Malec
· -->Committed to doing a draft this week.
· -->Will set up another special purpose meeting.
· Noted that for the most part, the content has been written and no one seems to disagree with it.
· Janet Campbell
· Confused about the extra Security document in the Documentation Priorities table.
John Moehrke
· Pointed out that document should be removed.
· The content of the document was folded a different version of another document.
Janet Campbell
API documents
· Sought clarity
o Is this documentation still coming out of the Reference Implementation WG?
o Was Andy Oram going to look at the documents?
Andy Oram
· Has not had a chance to look at yet.
Janet Campbell
· Listed the applicable documents as the JAVA API, CSharp API and Configuration guides.
Arien Malec
-->Will point Andy into the right direction to get started reviewing the documents.
Andy Oram
-->Will look at on Sunday.
Arien Malec
SMTP, SMIME and CERT Implementation Guide
· Asked if the document exists yet.
John Moehrke
· Offered that a shell of the document was made, but added that the over spec discussed earlier should supplant the SMTP, SMIME and CERT Implementation Guide.
Janet Campbell
-->Suggested WG come back to the content of this guide at a later date.
Email Client Configuration Guide
· Suggested that the document reference some of the Deployment Model language.
· Asked for clarification about the object of the document:
o Is this document about setting up your Thunderbird or other email client to be secure?
o If that is true, WG might need to wait until someone is deploying this model, and then write with them in mind.
Arien Malec
· Agreed but pointed out that the suggested approach would be very email client specific.
John Moehrke
· Presumes the document will mostly jump off to other source documents:
o i.e. “here are the things to keep in mind when reading the Thunderbird document.”
o Won’t explain how to configure the exchange, but will highlight the things to keep in mind when configuring an exchange.

Dragon Bashyam
· Offered that Pete Palmer (?) of an outside committee has initiated a discussion to document something similar to this Email Client Configuration Guide.
· -->Will reach out to Mr. Palmer.

Janet Campbell
· Suggested that if Mr. Palme wants to put something together, he should join the project.
Arien Malec
XDD Specification
· Reported that the spec is in decent shape, lacking only a couple more items.
· -->Needs to schedule another special purpose meeting.
· Karen added in references to other metadata attributes that they hadn’t covered yet.
· In current state, should be implementable, but it has not been completley finalized.
Karen Witting
· Pointed out that while the WG is making good progress on the differences of XDR, explanatory text about how to do things using XDR has not yet been written.
· Reminded WG that the plan was to make implementation really simple to do, rather than digging through a large number of documents.
· -->A week from now (2010-09-22) can start filling in the explanatory details, and will start with whatever is there, contributed by others.
· -->Encouraged others to work on in the next week.
Janet Campbell
XDD Developers Guide
· Still in skeleton form.
· Asked if the XDD Developers Guide is similar to the XDD Spec.
Arien Malec
· Thought the Developers Guide would be more of a guide to the reference implementation.
David Tao
· Agreed that WG has done a good job at filling in the blanks on the XDD Spec.
· Reminded WG that when pulling together from the XDR supplement, the whole idea was to pull the material out of ITI with some metadata, some abstracts and some use case.
o Thinks it is really more the non-technical aspects of the document that tie it together.
· -->David will work on the XDD Spec before Karen gets back.
o Will pull relevant parts of XDR literature and put it into NHIN Direct terms, then apply to the spec.
Arien Malec
· Suggested including of the work Keith Boone did on metadata.
David Tao
· Asked if that would confuse things.
Arien Malec
· Pointed to the blog post Keith Boone wrote, which is an explanatory text on how to construct metadata.
· Admitted it might be scope creep, but one of the challenges for anyone implementing XDR or XDD from scratch is deciphering the metadata.
· Cookbook might be out of date but is another great tool/model.
Janet Campbell
· Recalled that when she was looking at what Vassil wrote, she liked that she could see the big table and could figure out how to do the metadata.
Karen Witting
· There are lots of different ways to do this, and each person will be excited about a different method.
· Wants to be careful and discourage copy/paste.
· When looking at the current XDD Spec, can see that all of the content directly link to other relevant content on other pages.
· They have plans to improve, by pointing not just to the page but also to a section number.
· Warned to watch out for bullet lists where some content is relevant but not all.
Arien Malec
· Non-normative examples would also be useful.
Karen Witting
· Observes two main issues with metadata:
o (1) Large group of people don’t care how to code. They can use existing open source coding.

• • • But they still want to know, in a table of 100 entries, which 5 are actually relevant to me?

o (2) The other kind of people are coding from scratch.

• • • She doesn’t think WG should try to address and help those people.
    • IT has examples of how to code in the Volume 3 table, so WG can point them in that direction.

Janet Campbell
· As long as we can have precise and appropriate pointers to the information they want, it makes sense not to address their needs directly.
David Tao
· Raised concern that pointing instead of cut/paste can get messy when there is a section with 75% relevant and 25% not relevant.
o It could get cumbersome pointing out the relevant bits.
Arien Malec
· Suggested doing a first pass to see how the document is looking.
o If it is hard to read, WG can change it.
John Moehrke
· Noted that the spec should not be specific to XDD.
o XDM needs the same assistance, for example.
David Tao
· Clarifying: is this in Vassil’s table?
Arien Malec
· Vassil’s table has been updated by Karen, changing labels.
· Shows content constraints, i.e. “do this, don’t do that, draw from this table, etc.”
Karen Witting
· Explained that they are no longer using defaults.
o If something in the past was called “defaultable,” it can be omitted.
· Noted that if WG doesn’t have the content of the spec, they also do not have the specific associated data.
· Did not understand what Arien Malec wrote for “patient ID.”
John Moehrke
· Noticed that the earlier mentioned table is only for the use case when the NHIN Direct was sent as a bare file with no metadata, and then something has to figure out a way to send it through an XDR pipe.
· The process is not the same when a native XDR-speaking sender sends something outbound, or if the inbound component is a native XDR speaker.
David Tao
· Right now it just shows directional flow.
John Moehrke
· Pointed out that the table does not included when sending starts from an NHIN Direct recipient.
Karen Witting
· Good point. We forgot that.

John Moehrke
· That part of the process is only understood by us unless we document it.
Karen Witting
· Compared thee metadata discussion during this meeting to the discussion she is having with NHIN Exchange.
Janet Campbell
· Asked if she would call it a metastruggle?
Karen Witting
· She is trying to help both groups figure out how to document metadata.
· In the end, the best thing would be a joint NHIN metadata document, showing metadata at all levels: minimal, exchange environment, etc.
o Would be great to have one document.
· Wondered if the XDD Spec could turn into the XDD and Metadata Spec.
Janet Campbell
· -->Added document to the Documentation and Testing Works in Progress list.
o Objective of document: documenting for how can you take your existing implementation reference and translate it to be able to send/receive NHIN Direct messages?
o Assigned document to Karen/David/Janet.
· Pointed out there may also be a possibility for a metadata “metadocument” focusing just on metadata.
o Asked the group if they should list a metadata document separately.
Arien Malec
· If it falls out of the XDD, XDR document, it will. No need to create separately at this time.
Karen Witting
· XDD spec is only about how NHIN Direct is changing XDR to satisfy a specific use case.
· But really the same is needed for XDM, XDD, XDR in the NIHN Direct environment

Arien Malec
· Thinks the document could have a wider scope.
· àProposed renaming the document “XD* for Direct.”
Karen Witting
· Mentioned that she will probably want to reorganize the document now that it has been renamed.
· Asked David Tao and Arien Malec to do whatever work they could do on the document for the next week.
John Moehrke
· Believes the XD* for Direct Spec document should be at a level of detail deeper than th Deployment Models document.
o Deployment Models should be a jumping off point.
KarenWitting
· Will look at Deployment Models as a guide to see how deep the document goes into detail, and then will add deeper layers.
Arien Malec
· àNeeds to schedule a week from now.
· Thursday works best for Karen Witting.
Janet Campbell
NHIN Direct Overview
· Focus group is meeting on Friday to address feedback from the Call for Consensus process.
· Feedback and edits should hopefully be straightforward.
· Will let the group know when these edits have been made.
Policy Questions for Implementations
· Went out for consensus on Monday night.
· So far have gotten a few new questions that they had not thought about before.
John Moehrke
· Mentioned that a few more questions came up that same day at the Implementation Geographies WG meeting.

Janet Campbell
· Suggested revisiting this document every couple weeks, keeping the document live as the implementation geographies roll out.
· Reminded WG that this document is for the questions the NHIN Direct Project doesn’t have the answers to.
· Suggested that the document be owned by the Best Practices WG in the future.
Dragon Bashyam
Security Overview
· This week they became more comfortable with the content of the document, but there are more edits to me made.
· Projected completion by the end of the week, and hoped to send out for viewing next week before Consensus.
John Moehrke
· While they were editing came he noticed that the spec seems to act as a intermediate doc between the high-level security blurb in the NHIN Direct Overview and the technical spec within the spec itself.
· Mentioned that he added a “where should I go next?” bit.
o Suggested doing this for all documents, because readers might not always know which document(s) they should read next or which document(s) they should have already looked at.
Dragon Bashyam
· Would be like a document map.
John Moehrke
· People might want to learn more or think they’ve read it all already, but the document map might show them otherwise.
· -->Explained that he has already added a “where should I go next?” marker on the Security Overview document, but asked members to look at what he did, and to feel free to come up with a better idea.
Janet Campbell
Conformance Guide
· Clarified that the point of the document is verifying that everything works as one might expect.
Dragon Bashyam
· -->Agreed to structure this document according to the outcomes of the Deployment Models, after some of the other work has been finished.

John Moehrke
· Much of the content of the Conformance Guide would be folded into the greater spec document.
· Conformance Guide includes some of the parts missing from the security document, so they can be collapsed in.
· Pointed out that there are still not answers for how you would go about making sure that your deployment model is complete.
Janet Campbell
Implementation FAQ
· Someone from IMP Geographies had created a list of questions but she didn’t know where they went.
David Tao
· Said the FAQs were recorded in the Implementation Geographies group meeting, but he didn’t see them on the wiki.

Janet Campbell
· -->Will email Paul Tuten to request that the FAQs go on a wiki page.
· -->Will start tracking the status of each document in the document table on the wiki.
· Introduced the issue from the IG meeting about a common glossary from the NHIN Direct Overview document.
o Feels glossaries should be relevant to the individual document they are covering.
o Suggested putting together a glossary on the wiki so that all WGs could draw from whenever they needed glossary content.
Arien Malec
· Suggested calling the wiki glossary “Directopedia.”
Janet Campbell
· Asked the group if they should make it more efficient and accessible or consensus-based.
· Expressed concern that if something changed in the master it might trickle down to the other glossaries with the same content.
John Moehrke
· Suggested that glossary titles can link to the master glossary.
Janet Campbell
· Explained that the options are including all of the links and having messy content, or else using copy/paste which runs the risk of missing updates to the master glossary.

John Moehrke
· But what happens if at the time you copied the definition you liked it, but then it changes and is no longer as relevant to the document?
Will Ross
· Suggested that there may be some terminology drift during evolution of the project when documenting various features and functions.
o A single source repository of glossary terms will help writers because drift should be expected.
o Still, a definition might be tweaked if the master authoritative definition is not in sync with a particular document.
Janet Campbell
· Agreed. The goal is to make the glossary more self-sustaining.
· Asked if there is anything the WG members wanted to add to the list.
o Asked if anybody saw documents being left behind.
· Mentioned that she, Janet, is super busy next week.
Arien Malec
· Feels testing is being left behind but does not have ideas about how to approach.
Janet Campbell
· Asked what the basic idea of the Testing document would be.

Arien Malec
· More or less it would be about doing integration testing, two implementations talking to each other.
· What exists so far is unsatisfying.
Janet Campbell
· Asked if any WG members have the bandwidth to start thinking testing.
· Suggested reaching out to someone from Reference Implementation WG, the developers themselves.
o Was unsure what level of technical detail the document should reach.
· Asked if someone on both groups was interested in taking up the document.
John Moehrke
· Sees need for a high-level testing plan.
· For example someone might ask, “If I think I’ve implemented NHIN Direct, what can I do to make sure I have?” Answers:
1) Worked with ref imp
2) Does it work with thunderbird?
3) ...etc.
· The document should list off a high-level testing plan to validate if “you are highly likely to have done NHIN Direct right.”
Janet Campbell
· Suggested that because right now none of the WG has time to do this, they could see if any of the developers have time.
· If the developers cannot commit, WG can add to list of the next items to work on.
Arien Malec
· Liked John’s suggestion as a good start.
o Achievable in the short term.
John Moehrke
· Can be done in a page or two.
· -->Committed to creating a high-level testing guide.
Arien Malec
· -->Can look at, edit.
John Moehrke
· Mentioned that getting any deeper than the highest-level of testing would be difficult without the spec.
o The plan without the details should be fine at this point in time.
o Implementation geographies are wondering if they have something that looks NHIN Direct-ish.
o This high-level testing document is related to the deployment models so he can do both.
Janet Campbell
· Asked for other business, suggestions.
· Congratulated the team on a job well done.
To Do
1) -->Look at Deployment Models document.
2) -->Sign up for the Google Group so you are not left out of emails.