JoAnn, I am not sure that we disagree.
I think that it is vital that the spec contain well-written and
clear content. It's not there yet, and we are working to remedy that
as much as we can given the narrow runway for 1.3. (I think you know
how committed I am to good content ...)
But the primary goal of the spec must be to set out definitively the
core architecture and design, not serve as tutorial and training
materials.
I very much agree that the spec must not be so "obscure" that it
cannot be read; that will turn DITA into a dead standard.
But at the same time, the spec never will be accessible to everyone.
Children need to learn to crawl, then walk, then run -- someone new
to DITA will never be able to pick up the spec and read and
understand the topic that outlines what a constraint is and what it
does. And we cannot and should not author that topic in a way that
would be accessible to some one brand new to DITA; our audience are
informat
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 9:30 AM, Hackos, Joann
wrote:
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
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
|