[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: Options for DITA 1.3 packaging
Chet, just to clarify, the only "artifact" for which we would want HTML only is the landing page. This is the artifact that would point users to the following DITA 1.3 packages, for example:
- Base
- Technical communication
- Learning and training
- Semiconductor
- Light-weight DITA
- Complete
Please look at the prototype of a "landing page" that I sent to you. This is parallel to what the DITA TC did for DITA 1.1, when we had two different specification narratives: Architectural spec and Language Reference.
This landing page would NOT contain any of the specification narrative.
Does this work for you?
Best,
Kris
Kristen James Eberlein
Principal consultant, Eberlein Consulting
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 12/3/2012 2:40 PM, Chet Ensign wrote:
Hi Kristen, hi all - For your meeting tomorrow, here is a break down of the two options for packaging DITA 1.3: - Treat it as a master spec and a set of profiles or - Put everything together in one multi-part spec Also, one quick note: TC Process requires that all narrative specification documents be available in editable source, HTML and PDF. So those formats will be required - although I believe we have put the DITA XML as editable source into a ZIP file in previous releases. Key point here though is that we can't have just an HTML file at some point in the collection of files. Description of each approach... 1. Master spec and profiles In this approach, DITA v1.3 will contain the complete, master set of specification artifacts (narrative document, schemas, dtds, etc.) and the light-weight, community-focused versions will be treated as separate subsets or profiles -- peers to the main spec that are generated from the spec. Pros: - you can still generate the profiles from the full DITA source files - if you want to modify one of the profiles (for example, the Semiconductor subset) you can do that and approve it on its own, without having to completely reprocess the entire specification. (This could be particularly helpful once you reach OASIS Standard as a change to any one part would mean going all the way back to CSD and walking the full set of stages again.) Cons: - you have to approve and advance each with a separate motion and vote. Under this approach, the titles, file structure and file names would like something like this: docs.oasis-open.org -/dita -/v1.3 -/csd01 - DITA-v1.3-csd01.html (etc.) -/spec -/xsds -/dtds -/technical-communication -/csd01 - DITA-techcom-v1.3-csd01.html (etc.) -/spec -/xsds -/dtds -/examples -/semiconductors -/csd01 - DITA-techcom-v1.3-csd01.html (etc.) -/spec -/xsds -/dtds -/examples The cover page of each of the specs would refer to and link to the others in the "Related work" section. Here, the titles on each cover page would be something like: (for the core specification) Darwin Information Typing Architecture (DITA) Version 1.3 Committee Specification Draft 01 (for the profiles / subsets) Technical Communications Profile for DITA 1.3 Version 1.0 (or perhaps "DITA 1.3 for Technical Communications Version 1.0" ) Committee Specification Draft 01 2. Single, multi-part spec In this approach, DITA v1.3 is one master specification that contains both the full specification and the light-weight, community-focused versions. In this case, the light-weight versions are treated as parts of the master spec. Pros: - As above, you can generate everything from the source files - You can vote and advance everything in a single motion - In the file hierarchy, file names and titles, it is obvious that this is one spec Cons: - If you want to change *anything* you must advance the entire specification package as a whole. For example, if you decide to make an update to the Semiconductor part, you will then have to create, package, approve and put through public review the entire DITA 1.3 specification. Parts of a multi-part specification can't progress separately from the whole Under this approach, the titles, file structure and file names would like something like this: docs.oasis-open.org -/dita -/v1.3 -/csd01 -/part1-complete/ - DITA-v1.3-csd01-part1-complete.html (etc.) -/spec -/xsds -/dtds -/part2-techcom - DITA-v1.3-csd01-part2-techcom.html (etc.) -/spec -/xsds -/dtds -/examples -/part3-semicon - DITA-v1.3-csd01-part3-semicon.html (etc.) -/spec -/xsds -/dtds -/examples The cover page of each of the specs would, under "Additional artifacts" state that DITA v1.3 is a multi-part specification composed of... and list and link to the other parts of the specification. Here, the titles on each cover page would be something like: Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Communication Committee Specification Draft 01 Happy to go over this with you in person if you want additional explanation. Either one will work, in my view. It is just a question of which you prefer and find a better fit with your adopters. Best, /chet ---------------- Chet Ensign Director of Standards Development and TC Administration OASIS: Advancing open standards for the information society http://www.oasis-open.org Primary: +1 973-996-2298 Mobile: +1 201-341-1393
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]