Re: [dita] appropriateness of <dita> root element

[Michael Priestley <mpriestl@ca.ibm.com>]

Re:
>For meeting notes, white papers, and
a host of other things ditabase may be the best practice, 
>but those users and use cases are not
(correct me if I'm wrong) the primary target of the DITA TC.

The fact that we have an Enterprise Business
Document subcommittee suggests you're at least partly wrong. I think the
primary target of the DITA TC is modular content, which certainly includes
many tech pubs, but extends beyond it.

When we drafted the charter, we were actually
quite general on purpose, and deliberately avoided tying DITA to just tech
pubs in anticipation of its broader use:
http://www.oasis-open.org/committees/dita/charter.php

That said, I'm also not advocating ditabase
per se as a best practice - but having multiple topics in a single document
(at least at some stages of the content lifecycle) I think can be a best
practice, for specific scenarios and applications.

Michael Priestley
Lead IBM DITA Architect 
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

"Gershon L Joseph \[Yahoo\]" <gljoseph@yahoo.com>

03/26/2008 09:18 AM

To	"Ogden, Jeff" <jogden@ptc.com>, dita@lists.oasis-open.org
cc
Subject	Re: [dita] appropriateness of <dita> root element

I agree with Jeff. There will always be people
who do weird and wonderful things with DITA, and when what they do is correct
for their use cases, I'm not going to tell them they're doing the wrong
thing. Nor should the TC.

The problem is that the vast majority of new users are misusing DITA to
a point that they are often worse off than they were in Word or FrameMaker.
Most companies choose not to hire an expert to help them migrate to DITA,
and they get what they pay for. I'd like us as a TC (and moving forward
via the Adoption SC) to put tutorials, white papers, etc. in place to educate
new users to help them to do the right thing from the beginning.

We need to remain focused. Who is our primary target user group? What are
their use cases? AFAIK the answers are tech pubs groups documenting technical
documentation of hardware and software systems. For this user group and
set of use cases, ditabase is not a best practice (beyond perhaps a quick
and dirty migration path).

For meeting notes, white papers, and a host of other things ditabase may
be the best practice, but those users and use cases are not (correct me
if I'm wrong) the primary target of the DITA TC.

I think we'd do a service to the user community by removing those parts
that are not in sync with best practices for our primary target audience,
and put those parts up somewhere for download for use by those user groups
who have a good reason to use them. I'm not convinced we should continue
to bundle everything with the base DITA release.

At the same time, we must develop tutorials, white papers, and other guides
that cover as many use cases and user groups as we're aware of and address
their needs, suggesting best practices and, where relevant, providing unofficial
packages of DTDs and supporting code (e.g. DITA-OT plugins).

Gershon
 
Gershon L Joseph
Director of Technology and Single Sourcing
Tech-Tav Documentation Ltd.

Secretary, OASIS DITA Technical Committee
Secretary, OASIS DITA Translation Subcommittee
Member, OASIS DocBook Technical Committee


+972-8-974-1569 (direct)
+972-57-314-1170 (mobile)
http://www.tech-tav.com


----- Original Message ----
From: "Ogden, Jeff" <jogden@ptc.com>
To: dita@lists.oasis-open.org
Sent: Tuesday, March 25, 2008 9:23:59 PM
Subject: RE: [dita] appropriateness of <dita> root element

I don't really disagree with what Alan wrote
below.  There are cases where using ditabases or nesting topics make
sense.

 

The problem I've seen is that users and organizations that are new to DITA often choose to use ditabases or deeply nested topics for what I consider the wrong reasons.  Often the reason is that ditabases and nested topics are "easy" since they are similar to what they have been doing in Word or in docbook or in some other “traditional” tool. So they adopt a practice of using a ditabase or deeply nested topics without having to confront the issue of possibly needing to rewrite some of their content into a topic oriented style or to sort out mixed content within the same topic (the differences between concept, reference, and task). And they duck having to learn how to really use and benefit from maps.

 

The challenge for us is how to find a way to explain best practices as compared with what is simply allowed.  And we have to do this without confusing new users who may already be overwhelmed with too much new information as they are getting started.

 

This makes me think that new users should be encouraged to start off using maps and avoid using ditabases or nested topics. As they gain more experience they can choose to use ditabases or nested topics.  

 

For similar reasons I think new users should initially avoid the use of conref in maps and possibly conref entirely. Later as they gain experience they can choose to add the use of conref in topics if they wish.  And later still and with even more caution they can choose to use conref in maps.

 

    -Jeff

 

> -----Original Message-----

> From: Alan Houser [mailto:arh@groupwellesley.com]

> Sent: Tuesday, March 25, 2008 2:38 PM

> To: dita@lists.oasis-open.org

> Subject: [dita] appropriateness of <dita> root element

>

> I wanted to add a voice to the discussion towards the end of today's TC

> call about the effectiveness and appropriateness of the "ditabase"

> content model and approach to DITA adoption.

>

> Organizations deploy DITA for a variety of reasons. This may or may not

> include a need for topic-level content reuse. Not every organization

> will benefit from all of the capabilities of DITA.

>

> In deployments where topic-level content reuse was _not_ a driving

> factor, I've seen organizations struggle to map legacy content to DITA

> topic types, without a corresponding benefit. (Surely some benefit, but

> not clearly justified by the required effort to do so). I've also seen

> organizations compress migration time from years to months by mapping

> legacy content to the generic DITA "topic" type in nested structures.

>

> I'm troubled by the characterization that file structures which contain

> multiple nested topics are "not much better than Word."  The ditabase

> structure allows organizations to achieve multi-channel publishing,

> metadata- and output-based content filtering, and slashing of

> localizations costs through automated publishing, while minimizing the

> pain of legacy migration. As a TC, I think we need to take care not to

> belittle or discourage these benefits or this approach to migration in

> particular circumstances. Otherwise, we risk sending the message

> (implicitly or explicitly) that DITA is not appropriate except when

> substantial topic-level reuse is a requirement.

>

> -Alan

>

> --

> Alan Houser, President

> Group Wellesley, Inc.

> 412-363-3481

> www.groupwellesley.com

>

>

> ---------------------------------------------------------------------

> To unsubscribe from this mail list, you must leave the OASIS TC that

> generates this mail.  You may a link to this group and all your TCs in

> OASIS

> at:

> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php