This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "V3 Technical Editors Project FAQ"

From HL7Wiki
Jump to navigation Jump to search
Line 1: Line 1:
Back to [[V3 Technical Editors Project]]
==HL7 V3 Technical Editing Project==
==HL7 V3 Technical Editing Project==

Revision as of 15:29, 20 September 2007

Back to V3 Technical Editors Project

HL7 V3 Technical Editing Project

What is the reason for undertaking this project?

There is a perception in the marketplace that the standard is not implementable. Part of this perception results from issues with the documentation. These issues include both methodological problems (gaps or inconsistencies in what is written) and accessibility problems (documents and document sections written by different people at different times can be hard to read, sometimes as a result of divergent assumptions and objectives).

The immediate goal of the TE project is to address the well-known errors of omission, commission, consistency, etc. in the existing V3 documentation. The project's overarching goal is to help the organization probe deeper to clarify specific questions of the form “Is the problem with the documentation or with the underlying methodology?” It is only by having complete, accurate, and consistent documentation that this question can be effectively answered.

What is the project team charged with doing?

The team is charged with "editing the existing set of Version 3 documentation, and all subsequent iterations released to ballot during the contract period, to ensure consistency and coherency." (from the RFP, July 2006)

Who is involved?

Board of Directors: Sponsor project

Project Technical Lead (Charlie Mead): Provide direction from the Board of Directors

Advisory Group, including representatives from each steering division: Provide Stakeholder Feedback to the team

Ockham (the editing team): Plan and perform work

What are the Advisory Group responsibilities?

The Advisory Group is a consumer advocate organization. We need the members to

>Learn enough about the project to answer simple questions

>Listen to complex questions and concerns and bring them back to the editing team

>Attend a scheduled meeting once a month to report on questions and concerns

>Contact the editing team ad hoc for urgent issues

>Be willing to have their name published to provide these services

We expect the time commitment to run 2-3 hours per month. Significant issues should be conveyed to the team, not engaged by the Advisory Group.

Who is Ockham?

Ockham Information Services LLC is Jay Lyle and Sarah Ryan. We have retained the advisory services of Harold Solbrig and Abdul-Malik Shakir.

What does the team plan to do?

Because the documents are owned by their authoring committees, the editing team will not change the documents themselves, but rather make recommendations. We will work with the individual committees to work out the details, but there is a draft process document posted here.

What has the team found so far?

In a pilot effort this past spring, we found two kinds of issues. For methodological issues, it's clear that the authoring technical committees understand them; bandwidth is the problem. Accessibility problems arise from inconsistent author assumptions about audience and objectives, gaps and overlaps in boundaries between committees, and readers' ability to navigate the documentation as a whole.

Our committee already knows there are problems; how is this going to help?

For methodological issues, simply having an external pair of eyes can help clarify the problem, and having a maintained list will provide visibility and support prioritization.

For accessibility issues, we will provide emendations that the committee may accept, reject, or modify, and we will make recommendations regarding document structure and principles that will help decide whether to accept an emendation.

What is the approach?

Start at the core and work outward

Make document assumptions and objectives explicit

Edit for prose clarity; escalate methodological issues to the authoring committee

Clarify document boundaries to minimize repetition

What's not in scope?

Authoring new material

Solving substantive, modeling, and methodological issues

Dictating anything

What has been done so far?

Ockham has proposed a process, a user model, and a document map, and has conducted initial reviews of four documents:

RIM core classes

V3 Guide

SPL Implementation Guide

Vocabulary assets

These will soon posted for review and comment: please do.

Where can I go for more information?

Project documents will be posted on the Mayo Wiki for review. Ockham can be contacted at the e-mail addresses below. The Advisory Group can answer easy questions and bring harder questions to the team.

What's next?


Vocabulary documentation existing in the ballot

Data types

My TC is up next: what can I expect?

We'll meet to explain (and modify, if appropriate) our proposed user model and process. Then we'll need to prioritize the work, identify a point of contact, and collaboratively schedule our work activities.

How can I help?

Stay informed

Keep us informed via the Advisory Group

Review and preadopt the user model

Recommend documents and documentation issues for review

Thank you for your interest