------------------------------------------------------- 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.