OASIS Darwin Information Typing Architecture (DITA) TC

Here is the paper on Aggregated Editing for Electronic Business Documents
discussed in last week's meeting.  We are seeking your feedback, concerns,
issues, etc.  

Would it be possible to get your feedback by the end of March, the 31st? 

 -- Mr. Steven Manning*

The document named The Case for Aggregated Editing (The Case for Aggregated
Editing.doc) has been submitted by Mr. Steven Manning* to the OASIS Darwin
Information Typing Architecture (DITA) TC document repository.

Document Description:

A position paper describing the need for a mechanism for an aggregated
editing view of DITA topics.  This need is focused at Enterprise Business
users who are used to seeing content in context, not as individual topics.

View Document Details:
http://www.oasis-open.org/committees/document.php?document_id=31605

Download Document:  
http://www.oasis-open.org/committees/download.php/31605/The%20Case%20for%20Aggregated%20Editing.doc


PLEASE NOTE:  If the above links do not work for you, your email application
may be breaking the link into two pieces.  You may be able to copy and paste
the entire link address into the address field of your web browser.

-OASIS Open Administration

On 3/10/09 7:55 AM, "manning@rockley.com" 

Hi, Eliot.

The current DTD schemas (other than ditabase) allow only aggregation and
nesting of same-type topics: i.e. tasks within tasks, concepts with
concepts, etc. Hence, the need to use ditabase for aggregration of topics of
mixed types. How would one use a shell DTD to allow some arbitrary nesting
of mixed topic types in a document? And, perhaps more importantly, why
should we force users to design these shell DTDs?

Regards,
Tim
 



                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Tuesday, March 10, 2009 11:35 AM
To: manning@rockley.com; dita
Subject: Re: [dita] Groups - The Case for Aggregated Editing (The Case for
Aggregated Editing.doc) uploaded

On 3/10/09 7:55 AM, "manning@rockley.com" 

On 3/10/09 9:56 AM, "Tim Grantham" 

This perspective is exactly what has to change if we wish to see DITA see
broad adoption in the world of business narrative documents.

Users *do not* have to create local shells (for better or worse, we made no
changes to the default ones for Thermo LAI user guides, precisely because it
was so difficult to do so), not do they *want* to. They want to create
*content*, first and formost; everything else is a barrier to achieving that
desire, a barrier which will be ignored, resisted, or circumvented unless
they see a very compelling and immediate benefit to dealing with it. Having
to deal with DTDs and content management systems are enormous barriers to
broad adoption. Suppose a user of Word had been *required* to design a
template before they could create a document. Do you think that would have
encouraged broad use of Word?

I'm sorry if my tone is a little, how should I say, unmodulated, but I'm
passionate about this subject. Bringing XML to the world of business
narrative information has enormous potential benefits, and DITA is the best
candidate. But it has to compete with technologies that are much more
accessible to most users. The world has seen many standards designed by
specialists that ended up being of no use to anyone except the specialists:
Dewey Decimal System, OSI networking protocols, Esperanto... I don't want to
see DITA suffer the same fate. Standards that get adopted are simple, easy
to implement, and provide relatively immediate benefits -- HTML, TCP/IP,
SMTP -- and even they can take many years to achieve widespread use. In the
world of structured business narrative information, it isn't DITA or
sophisticated content management systems people are rushing to use today,
it's what looks easy and familiar: HTML, wikis, folksonomies, SharePoint...

We definitely need tools that make it easy for someone to rapidly design,
deploy, and manage DITA compliant DTDs without having to hire an information
architect to do so. Those tools have to provide element and attribute name
aliasing, easy subsetting of the DITA vocabulary (aka constraints), embedded
guidance for authors, and easy styling of outputs. Those tools don't exist
yet. Having the content management systems provide aggregation of topics for
editing and delivery and automated disaggregation is fine, but only the big
organizations and/or those with critical processes that depend on rigidly
structured narrative information will see that as providing a compelling,
immediate, and significant return on investment.

Any change we can reasonably make to the DITA standard to make adoption
easier should be seriously considered.

Regards,
Tim.



                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Tuesday, March 10, 2009 1:18 PM
To: tgrantham@timgrantham.com; manning@rockley.com; dita
Subject: Re: [dita] Groups - The Case for Aggregated Editing (The Case for
Aggregated Editing.doc) uploaded

On 3/10/09 9:56 AM, "Tim Grantham" 

In discussing this issue I think I've come to the realization that the
problem is not with any lack in the DITA specification or the DITA
mechanics.

The problem is simply this:

1. The use of DITA in the way envisioned by the Business Documents SC (and
by my Publishing clients) requires different configurations of nestable
topics than is provided by any of the out-of-the-box shells. This represents
a fundamentally different use pattern than that of most tech doc groups, who
focus on modularity and re-use. Nevertheless it is a perfectly valid DITA
use pattern and one that represents the quite possibly the largest potential
use pattern, given that the volume of business documents and Publishing-type
documents is orders of magnitude greater than the volume of technical
documents will ever be.

2. The syntactic mechanics of defining new configurations, while *as easy as
it could possibly be* in the context of DTD and XSD schema syntax, is still
beyond the reasonable capabilities of anyone who isn't an XML and DITA
specialist (or at least willing and able to work through my Specialization
Tutorial, which is still essentially everyone).

3. In the absence of a way to *easily* create local shells and, possibly,
local custom configurations, the use of DITA in any form for this
non-modular use pattern except via ditabase is simply unrealistic to expect
for any user community that is not at least large enough to have either a
dedicated tools person or budget to hire a consultant.

Note that the *practical* need to have local shells, even if they are merely
unmodified copies of the TC-provided shells, is simply a fact that stems
from the way XML works: if you change the configuration of a topic type's
shell it's a new shell and has to have a new name and that name is part of
the content of *every topic* of that type. This is coupled with the fact
that *you will want to change your configuration sooner or later*, if only
to remove those things you don't need from the default configuration.

My assertion that best practice is to create local shells as the *first act*
of production use of DITA is simply the logical implication of the fact
given above: Eat the cost as early as possible in order to avoid much
greater cost later. It's like changing the default password on your home
router (or DOT road signs).

But for Business Documents in particular, there is a larger problem: simple
copies of the base shells won't work because the default shells only allow
same-topic-type nesting. Using ditabase is at best unsatisfying because it
allows *all topic types* to nest.

Clearly Business Document creators need default shells (and specialized
topic types) that represent a reasonable balance between constraint and
flexibility but in any case allow a reasonable combination of topic types to
nest (e.g., reference and task topics within concept topics along with
probably some sort of generic "subsection" topic that avoids the whole
concept/task/reference distinction but is still a bit more constrained than

Is the following contradiction resolvable?

Eliot:
> *all* users of DITA should ... as a matter of standard 
> practice ... [be] creating local shell DTDs as the 
> *first step* of any production use of DITA.

Tim:
> Why should we force users to design these shell DTDs?

Is it a matter of different perceptions of who the DITA adopters are,
and their expected skill & knowledge level? (With the attendant
usability/adoption questions.)

Is CM the only motivation & usefulness for ditabase, as Eliot suggests
(below)? (CMS/elements vs. filesystem/documents.) Is there a reason that
ditabase should not be considered an out-of-the-box shell DTD?

> CMS systems, ... will 
> (must) have the infrastructure [for] e.g., generating a 
> single-instance document for editing and then breaking it 
> back up into individual topics. 

And then using the single-instance wrapper to persist that particular
higher-level organization of the topics? 

I like saying the CMS vendors have the responsibility to do all the
magic. I don't like depending on them to do it. As an alternative would
it be easier for them to support round-tripping between a map (for
publishing and to persist the higher-level organization into documents)
and ditabase (or a wrapper using a custom shell DTD) for authoring? We
have talked about the issue of persisting map-only attributes into a
ditabase document so they can be picked up on the return trip.

	/B

> 

                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----
> From: Tim Grantham [mailto:tgrantham@timgrantham.com] 
> Sent: Tuesday, March 10, 2009 11:57 AM
> To: 'Eliot Kimber'; manning@rockley.com; 'dita'
> Subject: RE: [dita] Groups - The Case for Aggregated Editing 
> (The Case for Aggregated Editing.doc) uploaded
> 
> Hi, Eliot.
> 
> The current DTD schemas (other than ditabase) allow only 
> aggregation and nesting of same-type topics: i.e. tasks 
> within tasks, concepts with concepts, etc. Hence, the need to 
> use ditabase for aggregration of topics of mixed types. How 
> would one use a shell DTD to allow some arbitrary nesting of 
> mixed topic types in a document? And, perhaps more 
> importantly, why should we force users to design these shell DTDs?
> 
> Regards,
> Tim
>  
> 
> 
Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Tuesday, March 10, 2009 11:35 AM
> To: manning@rockley.com; dita
> Subject: Re: [dita] Groups - The Case for Aggregated Editing 
> (The Case for Aggregated Editing.doc) uploaded
> 
> On 3/10/09 7:55 AM, "manning@rockley.com" 

On 3/10/09 2:23 PM, "Bruce Nevin (bnevin)"