I'm in favour of the spec being as simple
to understand as possible, but no simpler :-)
I'm also very aware of how different
the value proposition for DITA is in different circumstances. The reasons
people need DITA are as varied as the complaints that it's too complicated
(because one is the inverse of the other - one person's need is another
person's complication).
For example, some use cases are all
about dynamic aggregation based on metadata - maps exist as an output artifact
only, and aren't the place where relationships are defined by the author.
In other use cases content is authored
in small chunks and directly reused into other applications, like pulling
product descriptions from a database or glossary into various web pages.
So - I'm not averse to having good explanatory/introductory
material in the spec, but I think it's a tougher problem than it looks
like because different intros and value propositions work for different
audiences - and we don't have all those audiences represented on the TC,
in fact in some cases we may not even be aware of them.
Michael Priestley, Senior Technical
Staff Member (STSM)
Enterprise Content Technology Strategist
http://dita.xml.org/blog/michael-priestley
From:
"Hackos, Joann"
<>
To:
Kristen James Eberlein
<>, DITA TC <>
Date:
03/12/2015 09:34 AM
Subject:
Re: [dita] Purpose
of spec (was "Re: [dita] The whatever-we-call-it factor")
Sent by:
<>
Hi Kris,
I don’t think I agree with you. The way
we explain something to DITA users at lots of levels gives us valuable
insight into what really communicates the concepts. In working to make
the spec really communicate, it’s useful to know how various people explain
what is happening. If the spec isn’t communicating what people need to
understand, it’s obviously not working.
We cannot make the commentary in the spec
so “obscure” that we lose sight of the goal—successful implementations.
Given that many of the implementations are not successful and do not in
fact perform as the spec intended suggests that we haven’t met our goals.
Thanks for everyone weighing in on this.
So much of the spec is really difficult to understand.
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
CIDM will be hosting the Content Management
Strategies/DITA North America 2015 conference in Chicago, Illinois April
20-22, 2015. More information at:
http://www.cm-strategies.com/2015/index.htm
From: Kristen Eberlein <>
Date: Thursday, March 12, 2015 at 6:57 AM
To: DITA TC <>
Subject: [dita] Purpose of spec (was "Re: [dita] The whatever-we-call-it
factor")
Guys, I think we must draw a strict distinction
between what is appropriate in the spec and what it is appropriate in other
types of discourse about DITA: Opinion pieces, tutorials, teaching materials.
The DITA spec needs to set out the fundamental aspects of the architecture:
Core concepts and vocabulary
Explanation of fundamental features and
mechanisms
Definition of elements that comprise the
core and TC-approved specializations
Expectations for processors The
spec is not an appropriate place for opinion pieces and teaching material.
As someone who came from the ranks of information
developer and who continues to conduct DITA training, I certainly have
my own mental model of DITA -- and a framework that I use to introduce
DITA in training -- but I think my personal mental model and teaching framework
is something VERY distinct and separate from the spec.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 3/12/2015 6:36 AM, Dr. Stanley Doherty
wrote:
Hi Bob --
I like your approach very very much. When I teach DITA, I emphasize that
transformed output is not the "thing" by which we measure the
success or integrity of a DITA implementation. Your "information network"
thingie would give me a term for the DITA gestalt prior to it being transformed
into anything.
Hail "thingies"!! (or whatever we call it)
/stan
I have done a preliminary reading of the Linking topic cluster and Eliot's
email that we discussed last Tuesday. First, I believe that it's appropriate
to address the facets of DITA linking in a central place. It is the linking
that transforms a collection of resources into a useful DITA whatever-we-call-it.
There is enough complexity that a unified discussion is needed to furnish
context for the normative parts of the spec.
This "whatever-we-call-it" nomenclature is annoying, and I promise
not use again. But it emerged because the spec is a headless description
of DITA. It never really says what a DITA something-or-the-other is. One
consequence of this shortcoming is that there is no foundation to furnish
context when explaining DITA structure.
When I was a technical writer one of the most effective ways I found for
getting information from people was to just make something up, and then
ask them to approve it. In that spirit, I offer this attempt give the DITA
spec its head.
DITA is an XML vocabulary for creating content and then aggregating it
and other resources into a structured information network. Information
networks get created for some purpose. For example, an author could create
a DITA information network that includes all of the content and structure
necessary to publish a user guide for some product.
All relationships among resource entities that contribute to a DITA information
network are expressed through a combination of XML-element containment
(native structural relationships) and DITA linking-attribute values. An
information-network’s native structure is primarily defined through the
hierarchical arrangement of linking-elements contained within DITA maps.
Other forms of DITA linking allow a variety of non-structural content relationships
to be expressed.
Typically, a DITA information network starts within a specific DITA map.
A DITA map that serves in this capacity is known as a root map. A DITA
map that serves as a root map in one information network could also serve
as an information subnetwork in another information network. However, such
a DITA map would necessarily lose its status as a root map in that subordinate
context because it would no longer be the entry point for that information
network.
DITA information networks typically contain independent information subnetworks.
These subnetworks are bound together through the use of linking elements
within DITA maps. In some cases, these information subnetworks express
useful relationships that do not contribute to an information network’s
native structure. The following DITA constructs are examples of that: subject
scheme, relationship tables, and key definitions.
An information network may be also be constrained through filtering. With
filtering, one or more ditaval documents specify the filtering-conditions
to be applied, and selection-attribute values within DITA topics and DITA
maps bind filtering-conditions to content.
Best Regards,
--------------------------------------------------------------------- To
unsubscribe from this mail list, you must leave the OASIS TC that generates
this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
