Difference between revisions of "V3 Technical Editors Project FAQ"
| Line 83: | Line 83: | ||
Dictating anything | Dictating anything | ||
| + | |||
| + | |||
| + | '''Why isn't the project authoring anything?''' | ||
| + | |||
| + | It is very difficult for writers effectively to edit material that they have written. The assumptions authors make in composition that cause semantic gaps for readers are likely to remain assumptions when they edit. Having an editor who did not participate in the composition is critical to identify these gaps. | ||
| + | |||
| + | |||
| + | '''Why can't a technical writer do this?''' | ||
| + | |||
| + | This is as much a coordination and project management effort as text editing. The key issue is to identify the difference between writing problems and content problems: this must be addressed with the TCs. In addition, the team is looking holistically at V3 documentation to help enhance both completeness and conceptual and formal integrity. In order to accomplish all this, the project team is not just emending sentences: it is also producing editorial principles to guide the work with the collaboration of the TCs, a user model to guide the creation of document objectives and identify gaps in composition, a process involving retained experts to advise the team and review the work, and processes to manage the project across multiple TCs and other interested parties. | ||
Revision as of 01:42, 12 October 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 too difficult to implement. 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
Why isn't the project authoring anything?
It is very difficult for writers effectively to edit material that they have written. The assumptions authors make in composition that cause semantic gaps for readers are likely to remain assumptions when they edit. Having an editor who did not participate in the composition is critical to identify these gaps.
Why can't a technical writer do this?
This is as much a coordination and project management effort as text editing. The key issue is to identify the difference between writing problems and content problems: this must be addressed with the TCs. In addition, the team is looking holistically at V3 documentation to help enhance both completeness and conceptual and formal integrity. In order to accomplish all this, the project team is not just emending sentences: it is also producing editorial principles to guide the work with the collaboration of the TCs, a user model to guide the creation of document objectives and identify gaps in composition, a process involving retained experts to advise the team and review the work, and processes to manage the project across multiple TCs and other interested parties.
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?
The RIM
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
jlyle@ockhamis.com sryan@ockhamis.com
