Options for DITA 1.3 packaging

[Chet Ensign <chet.ensign@oasis-open.org>]

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