Groups - DITA TC minutes, 12 May 2009 (DITA_TC_meeting_12_May_2009.txt) uploaded

[keberlein@pobox.com]

-------------------------------------------------------
      OASIS DITA Technical Committee Minutes
                Tuesday, 12 May 2009
-------------------------------------------------------

Minutes recorded by Kristen James Eberlein.


1. ROLL CALL
Present: Robert Anderson, Stan Doherty, Rob Frankland, Paul Grosso, Elliot
Kimber, Chris Kravogel, Bruce Nevin, Dana Spradley, Su-Laine Yeo, JoAnn
Hackos, Gershon Joseph, Michael Priestley, Jim Earley, Don Day, Steffen
Fredericksen, Seth Park, Jae Sheddy. 

Quorum is present; 100% of voting members.


2. APPROVE MINUTES FROM PREVIOUS MEETING
*  http://lists.oasis-open.org/archives/dita/200905/msg00008.html (5 May
2009)
Motion made to approve minutes; seconded by JoAnn Hackos; motion carried by
acclamation.


3. SUBCOMMITTEE REPORTS
JoAnn Hackos reported that the Translation subcommittee is reviewing Kara
Warburton's best practice document on glossary.


4. ITEM: # ITEM: HREFS TO TOPICREFS (was "Cross-references to Topicheads
and Implicit Title-only Topics")
* http://lists.oasis-open.org/archives/dita/200905/msg00011.html (Eliot,
final position)
Elliot clarified that we now are explicitly stating that the behavior is
processor-specific; there are no technical changes, just documentation
clarification. Ready to be endorsed by the TC and submitted to the editors
for the specifications.
Don Day moved that the e-mail be forwarded to the editors, seconded by
Bruce Nevin; approved by acclamation.

Action (12 May 2009):
---------------------
Gershon Joseph and Robert Anderson, as editors of the specifications, to
ensure that appropriate changes to the documentation occur.


5. ITEM: MAPREF ATTRIBUTE RESOLUTION
* How does @scope behave when cascading from map to map? 
There is an open action for Robert Anderson:

Action (21 April):
------------------ 
Robert to write up summary based on 21 April discussions; vote when it is
posted.

Robert reported that he has not done this; he will send summary to this
list; it will be ready for vote next week.


6. ITEM: EDITORIAL STYLE
Action: Gershon Joseph will follow through on this by setting up the
sign-up page.
Kris Eberlein created a Wiki page at
http://wiki.oasis-open.org/dita/DITA_1.2_specifications%3A_Authoring_and_editorial_guidelines;
item is closed.


7. ITEM: THE CASE FOR AGGREGATED EDITING
* http://lists.oasis-open.org/archives/dita/200903/msg00014.html 
* http://lists.oasis-open.org/archives/dita/200904/msg00099.html (TSelf
comment) 
Deferred until Steve Manning is present. Members should read Tony Selfs
comment.


8. ITEM for 1.3: Element-to-Element Relationship Tables (ExternalLinks)
* http://lists.oasis-open.org/archives/dita/200905/msg00000.html (Kimber)
Marked as closed contingent on Gershon Joseph logging  this item on the
DITA 1.3 issues page.


9. New ITEM: PROCESSING-ROLE ATTRIBUTE (Anderson)
* http://lists.oasis-open.org/archives/dita/200904/msg00080.html
Robert commented that there had been clear discussion and general consensus
on the list that the default value for the keydef should be
resource-only.

Motion made by Robert Anderson that on the <keydef> element, the
processing-role attribute should default to resource-only. Seconded by
Bruce Nevin, approved by acclamation.

Action (12 May 2009):
---------------------
Robert Anderson to figure out if there are other outstanding issues
concerning this item.


10. New ITEM: CRITDATES REQUIRES CREATED (Kimber)
* http://lists.oasis-open.org/archives/dita/200904/msg00094.html and
following
The <critdates> element currently requires that you have a creation date;
Elliot Kimber has a client that wants to  use critdates but they don't
always have a creation date -- and they don't want to always have a
creation date. To Elliot, this seemed that DITA was imposing an
inappropriate business rule. Gershon Joseph commented that always having a
creation date made sense when DITA was fundamentally designed for technical
document; now that techcomm has been moved out from the base and
generalized for a broader audience, new use cases (such as this) are
arising.  
Don Day commented that this could be viewed not as a technical change but
as a relaxation of the content model. He asked whether this change is
attainable for the DITA 1.2 schedule? Paul Grosso commented that Arbortext
code just froze.

Motion made by Don Day on Elliot Kimber's behalf that the TC revise the
content model for <critdates> with appropriate revisions to DTDs and
documentation; seconded by JoAnn Hackos; approved by acclamation.


9. ITEM: WHAT SHOULD BE IN THE ARCHITECTURAL SPECIFICATION? (Eberlein) 
* http://lists.oasis-open.org/archives/dita/200905/msg00001.html
10. New ITEM: Specialization spec packaging (Kravogel via Gershon) 
* http://lists.oasis-open.org/archives/dita/200904/msg00075.html
Good discussion last week; item closed contingent on completion of open
action items from last week.

Actions carried over from previous week (5 May 2009):
----------------------------------------------------- 
1) Gershon to update the doctype shells page with feed back from Michael,
also to 1) add heading styles to make the collection headings clearer, and
2) clarify expectations for the various spec documents. Gershon and Michael
will include Robert Anderson and Jeff Ogden in this work, since they were
involved in the last changes to the page. 
2) Michael Priestley will draft a clear, crisp definition of the charter of
 the architectural spec; he also will draft a one-paragraph description of
each document, including the architectural spec.


10. ITEM: REVIEW MASTER TOPIC LIST--Gershon
Gershon directed people's attention to the Wiki page at
http://wiki.oasis-open.org/dita/DITA_1.2_specifications%3A_Authoring_and_editorial_guidelines;
he encouraged members to contribute comments and questions to the
work-in-progress. All authors, editors, and reviewers of topics should
become familiar with this page.

He noted that Kris had uploaded the Excel spreadsheet to SVN; be sure to
lock this file in SVN before making any changes.

There is a section titled "Audience and purpose for the architectural spec"
that contains talking points that  Gershon and Kris discussed last week; he
is also aware that Micheal Priestley has an open action item to draft
information about the charter for the architectural spec.

Gershon then raised the question of what should be in the Language
specification versus what is in the architectural spec; his personal
opinion is that the lang spec should discuss elements and attributes that
are in the DTDs and schemas; anything beyond that (processing expectations,
etc.) should be in the architectural spec. Right now there is a lot of
overlap; many topics in the lang spec go into more detail, and that detail
should  probably be in the architectural spec. He asked for discussion from
the floor on this point.

Elliot commented that this seemed like a reasonable break down. When he was
doing the research on the href item, he came on many places in the Language
Spec that said "See the architectural spec." While this is clumsy, it makes
sense to for a standard to centralize all of the complex processing
semantics in one place.

JoAnn Hackos commented that she agrees with Gershon and Elliot's comments.
She went on that a problem with the architectural spec, like any
dictionary, is that the content is disbursed. You cannot easily get a good
overview of how something is supposed to work. The Language spec also
suffers from the fact that it -- by its very nature -- does not explain how
things work together as a unit. She'd like to see the architectural spec
written from a user-oriented, scenario-driven perspective. If you read the
Yahoo! group, you see that users are beginning with a DITA implementation
when they don't understand how maps work. The architectural spec should
start with simple scenarios -- what are the basics of how maps function,
for example -- and then go into the more esoteric scenarios  for how people
might implement maps. Need to do this for each section of the
specification.

Don Day asked whether we had time to do something like that; general
consensus that we did not. Robert Anderson raised the point that the
audience for the architectural spec was not the end user but implementers
and tool vendors.

JoAnn Hackos raised the point that many implementers are single people in
companies, often end users; not every implementer is a consultant.

Bruce Nevin commented that he agrees that JoAnn is identifying an important
gap for documentation, but he is not sure that it needs to be filled by the
architectural spec. Maybe there should be another document to serve this
need.

Robert Anderson asked whether a scenario-driven document could be written
by the Adoption Committee; the architectural spec should be oriented
towards people implementing the tools that work with DITA, stating how each
piece should work.

Micheal Priestley commented that there should still be room in the arch
spec for usage information, to make sure that the implementers understand
what they are trying to implement. Don't need step-by-step instructions but
should have topics that describe the intended overall flow, how we
anticipate people using DITA, so that the implementers don't end up meeting
the letter of the law but missing the spirit.

Stan Doherty commented that the 1.0 and 1.1 architectural specs have been
used by end users. If we are changing the definition of the audience, we
need to explain that audience change and let people know where material
useful for user and soft-technical implementers has been relocated.

Don Day commented that the overview for the architectural spec is one place
where we should explain the audience change.

JoAnn commented that she has been moving information about minimalism and
where DITA came from; Michael commented that we had agreed that material
should be handled in the Tech Comm package.

Robert Anderson commented that it has always bothered him to put "See the
architectural spec" in the language spec; he is glad that delivering the
language spec and the arch spec together will enable linking between the
two documents.

Gershon commented that the specialization topics will be task-based, since
that is how Michael had reworked the TOC. He's not sure whether we need to
do the same sort of hand holding on maps.

Michael commented that someone implementing a specialization is *very much*
the appropriate audience for the architectural spec; someone authoring a
map is not. Yet implementers reading the architectural spec need to
understand how people will be authoring maps. He also thinks that usage
guides organized around communities (tech docs, business documents) seems
like a good fit for the Adoption Committee.

Don Day commented that we might have the opportunity to move information to
a different timeline by moving it to the Adoption TC; this would enable us
to refine our model for the architectural spec and language spec.

Gershon reminded people that we also will need to use the page for style
issues. Stan Doherty offered to send that guidelines that the Help
Subcommittee to Gershon and Kris.

Open question of whether the arch spec is authored using DITA 1.1 or DITA
1.2; Robert commented that the lang spec uses keyref heavily. Consensus to
use DITA 1.2 for the arch spec.

Kris asked that JoAnn check updated files into SVN, so that she can look at
those topics in conjunction with the updated map topics and start work on
editorial points. JoAnn commented that she was just back from vacation, but
would do so shortly. She has changed files and topic types, so she will
need to delete the old files from SVN and then add the new files.

Actions (12 May 2009):
----------------------
1. Kris to add an "Editorial guidelines" section to the Wiki.
2. JoAnn to update her files in SVN.
3. Kris and Gershon to update "Audience and purpose of the architectural
spec" based on today's discussion.
4. Stan Doherty to send the editorial guidelines for the Help Subcommittee
to Kris Eberlein and Gershon Joseph.

Meeting adjourned.

 -- Kristen Eberlein

The document named DITA TC minutes, 12 May 2009
(DITA_TC_meeting_12_May_2009.txt) has been submitted by Kristen Eberlein to
the OASIS Darwin Information Typing Architecture (DITA) TC document
repository.

Document Description:


View Document Details:
http://www.oasis-open.org/committees/document.php?document_id=32565

Download Document:  
http://www.oasis-open.org/committees/download.php/32565/DITA_TC_meeting_12_May_2009.txt


PLEASE NOTE:  If the above links do not work for you, your email application
may be breaking the link into two pieces.  You may be able to copy and paste
the entire link address into the address field of your web browser.

-OASIS Open Administration