I like JoAnn’s suggestion of a
readable overview to the functionality followed by the technical details. Unless
someone writes a comparable document in “user speak” DITA remains
inaccessible. This could be a job of the greater community and certainly offers
book opportunities, but a short overview would certainly aid in dissemination
of information.
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Thursday, October 01, 2009
11:12 AM
To: Joann Hackos
Cc: DITA TC
Subject: Re: [dita] Audience of
the arch spec
We already have a crisp definition of the audience:
http://wiki.oasis-open.org/dita/DITA_1.2_specifications:_Authoring_and_editorial_guidelines#Audienceandpurposeforthearchitecturalspec
- The intended audience of the architectural
specification is not a typical author or end user; the intended audience
is people designing tools that work with DITA. Such people need to
understand how the core elements of the DITA architecture work together.
While the architectural specification is not intended to provide
step-by-step instructions, it needs to contain enough topics that describe
the overall flow, so that tools vendors 1) will understand how people will
use DITA, and 2) will be able to properly implement the standard as
intended ("spirit not just letter of the law.")
There are always going to be places where the spec
needs to be geeky. One of the comments logged against DITA 1.0 as I recall was
that the description of how conref worked was horribly complicated, and would
scare users off, and that actually conref was really simple to use. (Which
hopefully it is, precisely because all that complexity is implemented by the
geeks who have to read that section).
If
the learning and training spec is directed at users, rather than implementers,
that may actually be a problem for it. Docs directed at users have different
concerns from docs directed at implementers (you can afford to be blurry about
the line between can/should for users - not so for implementers). I say this
from my own experience, adapting the DITA users guide I wrote for internal IBM
users into the first draft of the DITA spec aimed at external implementers.
If
you read the sections on conref, specialization, etc. from the perspective of a
user, they will be horribly unusable. But if we modified those sections to make
them end-user friendly, we would render them horribly unusable for their actual
intended audience: the programmers who will implement the behavior for those
end-users.
Michael
Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
|
From:
|
Joann Hackos <joann.hackos@comtech-serv.com>
|
|
To:
|
DITA TC <dita@lists.oasis-open.org>
|
|
Date:
|
10/01/2009 11:00 AM
|
|
Subject:
|
[dita] Audience of the arch spec
|
Hi All,
I continue to be concerned about our definition of the audience of the arch
spec. We seem to have two camps: the XML geeks and the user community
advocates. Certainly, the Adoption TC needs to direct explanations to the user
community, but does the arch spec need to be so completely obtuse?
In fact, it is quite schizophrenic. Read the Learning and Training arch spec.
It’s actually in plain language and speaks to the user community. Compare
that with some of the other sections, which should communicate to a broad
audience. Each section of the arch spec should have a user-friendly
introductory explanation of the feature (at least).
It seems that we are getting to sound more and more like software developers
who insist that the users know what wonderful, magical work they did in
creating the software. Makes the documentation unusable.
Just ranting, of course.
JOAnn