RE: [dita] Audience of the arch spec

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

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 
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

From:	"Ann Rockley" <rockley@rockley.com>
To:	Michael Priestley/Toronto/IBM@IBMCA, "'Joann Hackos'" <joann.hackos@comtech-serv.com>
Cc:	"'DITA TC'" <dita@lists.oasis-open.org>
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: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