OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Audience of the arch spec

We already have a crisp definition of the audience:

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

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.

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]