Next in thread →
Next in month →
RE: [dita] DITA 1.2 packages [updated again]
I’m not sure that a detailed description of the sort you are looking for is doable without knowing more about what applications the user is using (OpenTool Kit, XMetal, Arbortext, …) and what it is they are trying to do (what DITA doctypes they are using, what it is they need to adjust). If someone can write down a specific use case or two, I’d be willing to try to address that. A goal of the proposed packages is to provide one out-of-the-box doctype shell that includes everything that was included in DITA 1.1 in a DITA 1.1 doctype shell. In fact the proposed doctype shells generally provide a bit more than was included in DITA 1.1, but they don’t include everything that is new to DITA 1.2 in each doctype shell. Thus some of the Machine Industry work isn’t available everywhere, but is only available in the Machine Industry package. And the Learning and Training Content specializations are available in the Learning and Training Content package. Reading between the lines of your response it sounds as if you are more concerned about what is included in the doctype shells that are included in the out-of-the-box release from OASIS (item ii from my note) then you are about how many packages we have or what is included in which package (item iii) or about the division of the specification into smaller documents (item i). -Jeff From: JoAnn Hackos [mailto:] Sent: Monday, May 05, 2008 11:01 AM To: Ogden, Jeff; Subject: RE: [dita] DITA 1.2 packages [updated again] Hi Jeff, I guess what I’d like to understand in depth is the user experience with all of this. Is it possible to describe what will happen if someone gets a set that he or she needs to adjust, i.e., add one of the domains back in? A clear explanation of the user experience would help us decide if the packaging is a benefit or a detriment. Thanks for your continued thoughts on this. Best, JoAnn JoAnn T. Hackos, PhD President Comtech Services, Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 303-232-7586 joannhackos Skype www.comtech-serv.com From: Ogden, Jeff [mailto:] Sent: Monday, May 05, 2008 8:33 AM To: Subject: RE: [dita] DITA 1.2 packages [updated again] Any thoughts on the following? > In the packaging proposal there are (at least) three separate, but related things being discussed: > (i) There is the division of the documentation into a number of smaller subsets. > (ii) There is the structure of the directories that will hold the DTDs, XSDs, and related files. > (iii) And there is the packaging of all of that into a collection of individual zip archives plus two > combined zip archives (documentation and everything). > > Is it one particular item that is causing concern or is it all of them? > > And, if it is item iii (the number of packages) that is causing concern, would moving from 8 to 3 > or 4 packages help or do we need to get back to just a single package to resolve the concern? -Jeff From: Ogden, Jeff Sent: Tuesday, April 29, 2008 9:29 AM To: '' Subject: RE: [dita] DITA 1.2 packages [updated again] In the packaging proposal there are (at least) three separate, but related things being discussed: (i) There is the division of the documentation into a number of smaller subsets. (ii) There is the structure of the directories that will hold the DTDs, XSDs, and related files. (iii) And there is the packaging of all of that into a collection of individual zip archives plus two combined zip archives (documentation and everything). Is it one particular item that is causing concern or is it all of them? And, if it is item iii (the number of packages) that is causing concern, would moving from 8 to 3 or 4 packages help or do we need to get back to just a single package to resolve the concern? JoAnn asked: > Does the new packaging not require a significantly increased level of expertise to begin than we have had before? My own feeling is that there should be no more expertise needed with DITA 1.2 than with DITA 1.1 to achieve the same level of functionality that someone had with DITA 1.1 because we plan to deliver out-of-the-box document type shells that are very similar to the doctype shells that were included in DITA 1.1. Where the additional expertise comes in is if someone wants to customize their use of DITA in ways that weren’t pre-packaged. But that isn’t really anything new. And someone can avoid having to make any choices by using the combined package that contains everything and not doing any customization. DITA 1.2 does offer a number of enhancements that will require more expertise to use, but these are largely optional. One goal of splitting up the documentation and providing different packages was to allow users without the expertise or desire to use the new features to avoid having to deal with them. Not sure we have achieved that, but it was one of the goals. JoAnn also asked: > What packages are the editor and CMS vendors going to provide to their customers? How will they implement any or all of them? Aren’t we increasing the cost of entry and discouraging newcomers by making the choices too complex? Hopefully the editor and CMS vendors have enough expertise to make good choices. I think what we write into the DITA 1.2 Spec. as REQUIRED will have an impact on this, but that is something separate from packaging. I’d hope that the packaging wouldn’t drive decisions on the part of the vendors. Vendors are of course free to come up with their own packaging that may or may not be directly related to the OASIS convenience packaging as long as they correctly implement all of the REQUIRED portions. -Jeff From: JoAnn Hackos [mailto:] Sent: Monday, April 28, 2008 6:14 PM To: Ogden, Jeff; Subject: RE: [dita] DITA 1.2 packages [updated again] Well, I do think we have too many packages – all of these make the decisions for new users even more confusing than just downloading one package. It won’t be clear to newcomers what they’re getting or not getting if they aren’t already experts and/or consultants. What packages are the editor and CMS vendors going to provide to their customers? How will they implement any or all of them? Aren’t we increasing the cost of entry and discouraging newcomers by making the choices too complex? Committee members casually talk about creating new local shells but most of the people I know who are implementing DITA aren’t capable of doing any of that. Does the new packaging not require a significantly increased level of expertise to begin than we have had before? If this packaging was intended to make adoption easier, I feel we’ve gotten far away from that goal. We’re making adoption more complex instead. JoAnn JoAnn T. Hackos, PhD President Comtech Services, Inc. 710 Kipling Street, Suite 400 Denver, CO 80215 303-232-7586 joannhackos Skype www.comtech-serv.com From: Ogden, Jeff [mailto:] Sent: Tuesday, April 15, 2008 3:58 PM To: Subject: [dita] DITA 1.2 packages [updated again] Here is another version of the DITA 1.2 packaging proposal updated based on comments and suggestions received during today’s DITA TC call and subsequent e-mail to the DITA TC list. Changes from the previous draft are highlighted in blue. I’m sure this will be discussed again on next week’s DITA TC call. And comments and suggestions by e-mail to the list or directly to me (), Robert (), and Michael () are welcome. Questions: I. Should the Learning and Training topics and ditabase doctype shells include the software, ui, and programming domains? John thinks they should, but will check with the LTC subcommittee. This issue is settled until we hear back from the LTC subcommittee. II. Do we want a Learning and Training map doctype shell that is based on bookmap? John said yes. This issue is settled, we just need to do the work. III. Is it nuts to include so many variations of Ditabase doctype shells? Do we want a ditabase in each package? Should we leave this up to the sub-committees? We agreed to include just one ditabase as part of the Technical Content package. If the Learning and Training Content or the Machine Industry sub-committees want ditabases to be included as part of their packages, they can request that. We’ll assume that we don’t want or need the additional ditabases for these two packages unless someone speaks up. IV. Should we include the approved Best Practice documents as an informative part of the core package? Should we combine the existing best practice documents into a single document? We agreed to include the Best Practice documents in the documentation package as individual documents. V. Which map document type shells should include the Delayed Resolution domain? Basic map? Technical Content Map? Bookmap? Leaning Map? We agreed to include the Delayed Resolution domain in all map doctype shells unless a sub-committee explicitly asks for the domain to be omitted for map doctype shells included in their package. No explicit requests made yet, but its early. V. We have a constrained task doctype shell as part of the Technical Content Package. Do we need to include an unconstrained task? If so, in which package? Or is the Machine Industry Task an unconstrained task that can serve this role? The Technical Content package will include a constrained task doctype shell. The Machine Industry package will include a differently constrained task doctype shell. The DITA 1.2 release will not include a completely unconstrained task doctype shell, but individuals and organizations are free to create one if they wish. VII. Notice that the Delayed Resolution domain is included in the core package, that it is not included in any doctype shells. Is this OK? This is OK. VIII. Notice that the xNAL domain is included in the core package, but it is only included in the Bookmap doctype shell. We agreed to separate out the documentation for the xNAL package into its own Architecture and Language Reference document, to include this document and other xNAL files in the core package, and to create separate xNAL directories for DTDs and XSDs within the core package. IX. There was a suggestion that we have an additional package that would contain the combined documentation and none of the DTD, XSD, and related files. This is not included in the above proposal, but could be if members of the TC think it would be useful. We didn’t get to this item during today’s discussion, but while discussing other items the feeling seemed to be that we should have a separate combined documentation package and this would be the place to put the Best Practice documents together with all of the documents from the other packages. X. We will include the DITA source, PDF, and chunked HTML output. Do we want to include HTML Help (chm) and unchunked HTML output as well? We didn’t talk about this during today’s call, but I suggest that we include PDF output for the documents in each of the packages and that we include the DITA source, PDF, unchunked html, chunked html, and HTML Help output in the documentation package. XI. Are seven or eight packages too many (six individual, one combined, and possibly a combined documentation package)? We didn’t talk about this during today’s call, but so far at least no one has expressed concerns about the number of packages. XII. Questions about how to coordinate Robert’s proposed changes to the organization of the DITA Language Reference documents with the packaging proposal were raised during the 8 April DITA TC call. I’m no longer sure what the issue was here. Robert is going forward to implement (a prototype) of his suggested approach. I suggest that we came back and revisit this after that work is done. XIII. There is a question about the name for what is labeled the “core” package above. Is “core” OK or would “base”, “common”, or something else be better. We didn’t talk about this during today’s call. In a e-mail exchange with Robert and Michael I said I didn’t like “common” since we already have common files (common to topics and map) and so having a package named common might lead to “common common files” which would be confusing. I think we are going with “core” for now. If someone has strong feelings about this, they should speak up and hopefully offer suggestions for a new/better name. XIV. There are questions about the right place to put the xNAL and Hazard Statement domains that we need to sort out. We talked about this indirectly. We seem to be leaning toward putting the xNAL and Hazard Statement domains in the core package, but with a separate document to describe xNAL. The xNAL domain will be used from the bookmap doctype shell. The Hazard Statement domain will be used from several doctype shells in several packages. XV. Is Technical Content a good name for item #2 above? Would Technical Publications be better? Something else? The view was expressed that Technical Content isn’t a good name. No suggestions for an alternative so far. Not sure if Technical Publications or TechPubs is better or not. Probably not. We’ll probably stick with Technical Content until someone suggests an alternative. XVI. Not sure we have agreement on item xii below. General comments: The proposal is to organize the DITA 1.2 specification into a set of six individual packages plus a documentation package plus a combined package as outlined below. All packages include both DTD and XSD doctype shells and modules. All packages include catalog files (both XML and text). All packages include PDF output for the documentation specific to that package. The documentation package includes DITA source, PDF, chunked HTML output, and HTML Help (chm) and unchunked HTML output. The combined package includes everything. Packages will contain a mix of normative and informative (non-normative) materials. Directories and files will be organized and named so that they can be combined and installed into the same directories without conflict. Except for the documentation and the combined package, individual packages won’t duplicate the content from other packages. The Core Package can be used by itself. Each of the individual non-core packages requires the Core package and may require other packages. The Core Package plus the Technical Content Package gives what is available in DITA 1.1 without bookmap and with the addition of the Hazard Statement domain, the Delayed Resolution domain, and the Basic Topic and Basic Map document type shells. The written specifications, references, and guidelines are being divided into smaller independent documents to make them more manageable, to allow them to be maintained somewhat independently, to allow readers to avoid sections that they may not need or may not be interested in, and to make it easier to add more structural and domain specializations in the future. The DITA TC and eventually OASIS will be asked to approve the specifications, DTDs, XSDs, modules, and related files in the combined package. 1) Core Package a) DITA 1.2 Core Architectural Specification (introduction, topic, map, and metadata markup, processing including delayed resolution, specialization including constraints). b) DITA 1.2 Core Language Reference (map, topic, metadata including delayed resolution, map group domain). c) DITA 1.2 Utility Domain Specializations Architecture and Language Reference (utilities, highlighting, and hazard statement domains). c.1) DITA 1.2 xNAL Domain Specializations Architecture and Language Reference. d) DITA 1.2 Processing Guidelines and Examples (non-normative). e) Basic Topic document type shell (topic type, no domains). f) Topic type modules. g) Topic domain specialization modules for the indexing, utilities, highlighting, and hazard statement domains. h) Basic Map document type shell (only map type plus the map group domain). i) Map modules. j) Map Group domain specialization modules. k) Delayed Resolution domain specialization modules. l) xNAL domain specialization modules. n) ditaval document type. 2) Technical Content Package a) DITA 1.2 Technical Content Architecture and Language Reference (concept, task, reference, glossary). b) DITA 1.2 Software, Programming, and User Interface Domains Specializations Architecture and Language Reference. c) Topic document type shell (topic plus core topic domains plus the software, programming, and UI domains). d) Concept document type shell (concept plus core topic domains plus the software, programming, and UI domains). e) Glossary document type shell (glossentry plus core topic domains plus the software, programming, and UI domains). f) Reference document type shell (reference plus core topic domains plus the software, programming, and UI domains). g) Task document type shell (constrained task plus core topic domains plus the software, programming, and UI domains). h) concept, glossary, reference, and task specialization modules. i) Software, programming, and UI domain specialization modules. j) Map document type shell (map plus map group, delayed resolution, and indexing domains). k) Technical Content Ditabase doctype shell (topic, concept, glossentry, reference, constrained task plus the core topic domains plus the software, programming, and UI domains). 3) Book Package a) DITA 1.2 Book Architecture and Language Reference (bookmap). b) Bookmap document type shell (bookmap plus map group, indexing, delayed resolution, and xNAL domains). c) Bookmap specialization modules. 4) Learning and Training Content Package a) DITA 1.2 Learning and Training Content Architecture and Language Reference. b) Doctype shells for all of the Learning and Training topic specializations except learningBase, includes the core topic, software, programming, UI, Learning topic, and Learning Metadata domains. c) Learning and Training topic, map, and metadata domains. d) Learning and Training map doctype shell (map plus the map group, delayed resolution, Learning Map, Learning Metadata, and Learning topic domains). e) Learning and Training bookmap doctype shell (bookmap plus the map group, delayed resolution, Learning Map and Learning Metadata domains). f) Learning and Training map domain specialization modules. 5) Machine Industry Package a) DITA 1.2 Machine Industry Architecture and Language Reference. b) Machine Industry Task doctype shell (constrained task plus the core topic and Machine Industry domain specializations). c) Machine Industry domain specialization modules. 6) Semantic Linking, Controlled Values, and Taxonomies Package a) DITA 1.2 Semantic Linking, Controlled Values, and Taxonomies Architecture and Language Reference. b) Subject Schema Map document type shell (need details here). c) Subject Schema Map modules. d) Classification Map document type shell (need details here). e) Classification domain specialization modules. 7) Documentation Package a) The DITA source plus PDF, chunked HTML, unchunked HTML, and HTML Help output for all of the Architecture, Language Reference, Guideline, and Example documents from the other packages. b) The source and all outputs for all of the approved Best Practice documents as individual documents. 8) Combined Package a) All of the above in one combined package.
Next in thread →
Next in month →