This discussion reflects the
lack of intro/overview documentation for end users. That lack is not a fault of
the arch spec. Maybe the intro/overview portions of the lang spec should be
expanded. It's directed more at DITA users.
I have been reviewing the
L&T section. In my comments on the wiki I didn't say a lot about the
fact that it is constructed using the resources of the L&T specializations
and exemplifying the writing style of its users. Some of this content probably should migrate out of the arch spec into a
separate intro/overview doc. However, much of it does say how the
L&T specializations and "the core elements of DITA architecture work
together". Someone more concerned with tools implementation than I must review
it to verify that it "describe[s] 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...."
/Bruce
From: Michael Priestley
[mailto:]
Sent: Thursday, October 01, 2009 11:24
AM
To:
Cc: 'DITA TC'; 'Joann
Hackos'
Subject: RE: [dita] Audience of the arch
spec
I agree with JoAnn's suggestion re
the intro/overviews. They can't hurt. As long as the actual audience of the
spec is kept in mind. If it comes to a choice between audiences, the geeks win
for the technical spec. Just like the users win for any deliverables from the
Adoption TC.
Michael Priestley,
Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
http://dita.xml.org/blog/25
From:
"Ann Rockley"
<>
To:
Michael Priestley/Toronto/IBM@IBMCA,
"'Joann Hackos'" <>
Cc:
"'DITA TC'"
<>
Date:
10/01/2009 11:19 AM
Subject:
RE: [dita] Audience of the arch
spec
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:]
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
http://dita.xml.org/blog/25
From:
Joann Hackos
<>
To:
DITA TC
<>
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
