OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Groups - Authoring team meeting, 2 July 2009 (Authoring_Team_2_July_ 2009.txt) uploaded

    Posted 07-06-2009 17:06 
    -------------------------------------------------------
      Authoring Team Minutes
      Thursday, 2 July 2009
-------------------------------------------------------

Minutes recorded by Kristen James Eberlein.


1. ROLL CALL
Present: Kristen Eberlein, Gershon Joseph, Erik Hennum, JoAnn Hackos
Regrets: Robert Anderson, Elliot Kimber, Michael Priestley


2. PROGRESS OF THE REVIEW
Erik Hennum stated that Robert Anderson and Eric Sirois need to review the
topics about constraints. 

Kris Eberlein expressed concern that one of the assigned reviewers (Jim
Earley) has not yet completed any reviews. Since this involves significant
areas -- Overview, introduction, processing, and specialization -- we need
to get a new reviewer in place for this content. This is key since he is
the only assigned reviewer for some sections. Gershon replied that PTC will
be reviewing most content, and that he and Michael will be going through
everything.

Kris reiterated that she thought we needed to assign a new reviewer to
Jim's sections if he is not able to review the content; we need to have
someone committed to reviewing the content both for this review and the
following one. Gershon suggested that we see how much work he and Michael
are able to do over the weekend, then bring it up at next Tuesday's TC
meeting. If Jim cannot review the material, we'll ask for new volunteers.


3. SECTIONS OF THE ARCH SPEC THAT ARE NOT YET WRITTEN OR ASSIGNED TO A
WRITER
Kris Eberlein stated her concern that when the TC submits DITA 1.2 for
public review, the package needs to contain complete architectural
information, not just base architectural information. Therefore, we need to
have content written for each of the specializations: technical comm
content, learning & training, machine industry, whatever. Handling this has
not been something that we have paid ANY attention to.

JoAnn Hackos volunteered to take responsibility for the tech comm content,
and asked whether John Hunt had contributed any material.

Kris reported that she met with John Hunt and Robert Anderson yesterday, to
discuss possibilities of merging language reference and arch specification
material; this was a follow through to the action item that she accepted at
the TC meeting on 30 June 2009.

JoAnn commented that both Chris Kravogel and John Hunt had volunteered to
write feature descriptions for the Adoption TC; such material should work
hand  n hand with arch spec, but neither have produced work for the
Adoption TC yet.

Gershon stated that he thought this needs to be an agenda item for the next
DITA TC meeting. We need to reach out to the SC chairs, asking them to
provide whatever content they currently have. Kris expressed a concern that
SC material needs to be written by the SC, not folks currently working on
the base spec material. (Slightly different for Tech Comm, since the
committee is not yet formed.)


4. FORMAT FOR WHAT WE INCLUDE IN THE NEXT REVIEW
Kris expressed concern that the discussion about the unwritten sections of
the arch spec overlaps with the messy decisions about packaging. She then
stated that one of the documents that she has prototyped is a CHM that
contains both ALL arch spec and ALL lang ref material; perhaps this is what
the DITA TC should use for its next review.

Gershon stated that he thought not, we need to get to the packaged specs,
because he thinks the TC needs to see what is currently planned for the
individual specs. If we put everything together and then pull it apart,
things might fall apart. Everything has to be in place for the public
review, but for the 2nd review, we should focus on the base spec -- then
focus on the other spec docs. There are going to be challenges associated
with having separate documents, and the earlier we identify the challenges
and deal with them, the better we'll be.

Kris stated that she didn't disagree, but after prototyping some separate
documents (and a combined version), she's halfway convinced that having
people look at the combined document might help drive decisions about
packaging. When she looked at a prototype of the combined documents (using
stub files for the specializations), she thought it might:

	* Help us get all architectural spec content (technical content, machine
industry, whatever) written and reviewed before we send DITA 1.2 out for
public review
	* Help us figure out and implement the best strategy for handling
overlapping content between the architectural spec and language reference
topics
	* Help us make final packaging decisions

Gershon stated "Yes, it might make identify holes," but if we send out a
combined version (lock, stock, and barrel), will it confuse people given
that we have talked about separate packages? We should discuss this at the
TC level.

Kris: One problem with reviewing a completed, combined document is that it
would be much harder to set up review pages for *all* the lang ref
topics.

Gershon: Add this as an item for the next TC meeting, see if TC would agree
to use a big combined document for review and deal with chunking as we get
closer to the public review.

Kris: I'll sent you all a copy of the e-mail that I sent Robert and John,
complete with prototypes.

Gershon: Was trying to put DTDs in a spreadsheet, to understand what was in
what package, and saw discrepancies between what was on Wiki review page
about packaging and what actually was in DTDs. Wiki page on packaging is
out of date, and we need to close that gap. He was trying to understand DTD
packaging and let it drive documentation packaging decisions.

Kris: Packaging a murky area, decisions half-made and half-forgotten.

JoAnn: This also hinged on the ability of people to use a Web tool to build
doctypes.


5. STRATEGY FOR HANDLING AND IMPLEMENTING OVERLAP BETWEEN THE LANG REF AND
ARCHSPEC
Gershon: Work in progress. Kris will be uploading the lang ref topics to
Subversion.

Kris: There is duplication of material, since the lang ref and arch spec
were previously written by different people. Robert is concerned because
material (about keyref) was moved into the topics that Nancy Harrison was
responsible for. We need to be thoughtful about how we are handling
material and where we are conrefing. Can't be perfect for this release, but
maybe we can start to handle it in a way that we can improve in the future
-- and avoid cut-and-pasting. And avoid contradictory material.

Gershon: Need to have people do a complete read through. Better to delay
spec for an month and get it right.

Kris: In the middle, want to have deadlines and we'll do what we can in the
particular time frame. The release is already a year behind, and people are
hungry for it. We just cannot make it perfect.

Gershon: It needs to be good enough that we don't turn people off DITA.

Gershon: We *do* need to move lang ref stuff out of the arch spec, and arch
spec stuff out of the lang ref.

Kris: getting all files into Subversion will help with this; we need to
encourage all SC folks to upload files into Subversion.


6. REVISION MARKING
JoAnn asked at what level we should mark revisions. Gershon stated that we
should mark all changes coming out of the 1st review with @rev="1.2.1",
since it will make it easier for people who reviewed the first draft. 


Meeting adjourned.


 -- Kristen Eberlein

The document named Authoring team meeting, 2 July 2009
(Authoring_Team_2_July_ 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=33254

Download Document:  
http://www.oasis-open.org/committees/download.php/33254/Authoring_Team_2_July_%202009.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


  • 2.  RE: [dita] Groups - Authoring team meeting, 2 July 2009(Authoring_Team_2_July_ 2009.txt) uploaded

    Posted 07-06-2009 18:41 
    I share Kris's concerns about the review of Jim Earley's sections - particularly of those on specialization etc to which I'm also assigned.

These sections were some of the last to be made available for review, after months of delay. Indeed, I'm not sure we've even had a full two weeks to review them.

I think we need to discuss setting some new deadlines next meeting. These are important sections, as deserve a thorough vetting.

--Dana


    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 3.  RE: [dita] Groups - Authoring team meeting, 2 July 2009(Authoring_Team_2_July_ 2009.txt) uploaded

    Posted 07-06-2009 20:08 
    Kris corrects me: these sections were all delivered by the 16th.

So we have had almost three weeks now to review them.

It is true, however, that these all came in a flood at the end - while other sections have been trickling out for months now, making the reviewers' work loads easier to handle - especially given that we're now in summer vacation season.

Is Jim on vacation? Does that account for his missing this window?

In any event, it seems we need to set a new deadline for reviewing these sections, given that Jim did not perform the task in the alloted time.

--Dana


    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 4.  RE: [dita] Groups - Authoring team meeting, 2 July 2009(Authoring_Team_2_July_ 2009.txt) uploaded

    Posted 07-07-2009 02:58 
    All,

My apologies for any delays.  I have not had much time to devote to TC-related work over the past several months with my schedule.  That said, the next week is clear
and I will dedicate time to reviewing the sections assigned to me.

Thanks

Jim



    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


Related Content