RE: [chairs] Why the DITA Adoption TC cares about "templates"

["Kristen Eberlein" <keberlein@sdl.com>]

Hi, Jeff.

Remember that the DITA Adoption TC does not produce specifications. (The DITA TC does, of course, and we provide our specification in editable source (DITA), XHTML, CHM, and PDF.)

The older versions of the TC Process were rather mute about TC work products that were not specifications, such as the "feature articles" that the DITA Adoption Committee produces. Being good, process-minded campers, we asked Mary McRae how these articles needed to look and in what output format; she pointed us to the OASIS white paper template for PDFs, and away we went.

As far as I can tell, OASIS only has two adoption committees:

* OASIS OpenDocument Format (ODF) Adoption Technical Committee
* OASIS DITA Adoption Technical Committee

The ODF Adoption TC produced a white paper in 2006; it is available from the committee's public page in both ODF and PDF format. The DITA Adoption TC produced ten white papers between September 2009 and November 2010; PDF versions of the white papers are available from the TC's public page. (I cannot find any mention of OASIS white papers being provided in editable source, XHTML, and PDF; if anyone else is aware of such, please let me know!)

Now, with the new processes and the non-standards work track, there are three new work products: Basic, white paper, and presentation. Each must be produced in editable source, XHTML, and PDF. Currently, there are no publically available definitions of what content such work products should contain or how each work product should be styled and formatted.

The DITA Adoption TC doesn't mind producing documents in multiple output formats; delivering from one single source to many output formats is one of the core strengths of DITA. The DITA Open Toolkit -- an open-source implementation of the DITA standard that we use for publishing -- supports all the following formats:

* XHTML
* Compiled help (CHM)
* Eclipse help
* PDF
* TROFF
* RTF
* Docbook
* JavaHelp

So, writing CSS and tinkering with our Ant build scripts to produce properly formatted XHTML *theoretically* is a very straight-forward matter. *Practically*, it's something that we cannot do without having information about how the XHTML should be formatted.

The existing OASIS white paper style is very print and paper-oriented. Look at http://www.oasis-open.org/committees/download.php/35766/glossary_and_term_management.pdf , for example.

Here are the sort of questions that I want answers to:

* In XHTML output -- where you don't have pages -- do we need to have the vertical yellow line that is displayed on the PDF cover page? If yes, what is the precise color,  where should it be positioned, and how long should it be?
* What sort of table of contents is required? How many levels should it contain?
* For long white papers, when should we use multiple pages in the XHTML output? And if we do, what content do we need to have in the footers for individual pages?
* Should the sections of the white paper be numbered, so that precise sections can be identified in the XHTML output? While content in a PDF can be identified by reference to a page number -- "See the "Examples" section on page 95" -- the same content rendered in XHTML output is trickier, especially if a white paper contains multiple "Examples" sections.
* How and where should the new committee note metadata be displayed?
* Et cetera

Starting to develop an XHTML style without having these questions answered absolutely guarantees churn. How many of us in our "day jobs" would blithely sign off on a development project where the requirements and criteria are obviously vague or unstated? 

Best regards,
Kris
Co-chair, OASIS DITA Technical Committee
Charter member, OASIS DITA Adoption Committee

Kristen James Eberlein l DITA Architect and Technical Specialist l SDL Structured Content Technologies Division l (t) + 1 (919) 682-2290 l keberlein@sdl.com
 
Please consider the environment before printing this e-mail


-----Original Message-----
From: Jeff Mischkinsky [mailto:jeff.mischkinsky@oracle.com] 
Sent: Thursday, December 23, 2010 2:11 PM
To: Kristen Eberlein
Cc: chairs@lists.oasis-open.org
Subject: Re: [chairs] Why the DITA Adoption TC cares about "templates"

hi kristen,
   one clarification below
On Dec 17, 2010, at 2:37 PM, Kristen Eberlein wrote:

> Based on off-list e-mails, I thought I should clarify some issues:
>
> ˇ         The DITA Adoption TC authors its white papers in DITA.
> ˇ         The new processes now require us to provide editable  
> source, PDF, and XHTML for the white papers.

I don't believe this is a new requirement. I searched back, and found  
the requirement going all the way back to the August 2006 version of  
the TC Process (where i stopped searching).
Whether it's been enforced is a different question. ;-)

For the record:  all the previous versions of the TC Process can be  
found on linked from http://www.oasis-open.org/committees/process.php

cheers,
   jeff

> ˇ         We cannot code the necessary transformations for XHTML  
> without knowing what the requirements (font, font size, font weight,  
> headers, footers, tables, etc.) are.
> ˇ         We want the requirements to be defined and stable:
> o   We want to have a clearly specified set of requirements so that  
> we can ensure that our work products meet them.
> o   We do not want to have to redevelop the transformations except  
> at specified and set intervals.
> Best regards,
> Kris
> Co-chair, OASIS DITA Technical Committee
> Charter member, OASIS DITA Adoption Committee
> Kristen James Eberlein l DITA Architect and Technical Specialist l  
> SDL Structured Content Technologies Division l (t) + 1 (919)  
> 682-2290 lkeberlein@sdl.com
>  <image001.jpg>
> Please consider the environment before printing this e-mail
>

--
Jeff Mischkinsky			          		jeff.mischkinsky@oracle.com
Sr. Director, Oracle Fusion Middleware 				+1(650)506-1975
	and Web Services Standards           			500 Oracle Parkway, M/S 2OP9
Oracle								Redwood Shores, CA 94065