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

Hi Michael:

I read JoAnn as indicating more a shift in focus and approach than necessarily a change in the actual technical content, the technical coverage being a hard core requirement regardless. Having worked at a company with a developer audience and currently serving an implementer audience, there are ways to make technical information more "user" friendly, both for more and less technical representatives of the same audience. (I have found that there is usually a sliding scale of proficiency in any technical audience.)

For instance, a general-to-specific strategy with overview for every section is certainly a good start. Sometimes a lifecycle overview is helpful if a lifecycle is involved (most implementation projects do follow a particular course of action). Sometimes additional deliverables are required to put it all together, perhaps the purvue of the DITA Adoption TC.

I'm sure I'm preaching to the choir.

In terms of the Learning and Training material, we're obviously leveraging the existing DITA framework and benefit from work already done. We can take it for granted that our audience already knows something about DITA, however they learned it.

Our initial L&T user focus (John Hunt can correct me if I'm wrong) is: users of the specialization, which would include implementers, vendors, and potential end users. Though at this point, an end user would have to be somewhat geeky until authoring tools support the L&T spec directly. Nevertheless, a user or implementer of the specializaiton should not have to be a programmer to implement the specialization for their site.

In terms of the implementer audience for DITA, I disagree that implementers are neccesarily programmers. I am not a programmer myself and I've also worked on a custom structured XML implementation pre-DITA. Scripting languages, XML, and HTML, while requiring a minimum technical proficiency, have opened up easily accessible programmatic techniques to non-programmers. (Well, maybe not always so easy, but certainly accessible with enough hard work and empirical trial and error.)

Working on a DITA implementation now, I see no reason at all why a non-programmer could not implement DITA. In fact, in some cases, given the content "logic" embedded in DITA, it might be better if non-programmers did implement DITA for their sites so as to emphasize the content approach for writers as opossed to the technical underpinnings, which are easily subverted. I have worked with technical resources on XML implementations who couldn't care less about content approaches.

As it happens, the current implementer audience for my group are business analysts, not programmers, but they play with XML and HTML, along with some scripting to implement business rules. The focus of the content is different than if we were directing our content to computer science majors with an already existing technical understanding of object orientation, inheritence , overrides, etc. The technical information is still there, but the focus is definitely different.

My original read of the DITA spec some years ago was that the original audience of DITA pre-OASIS were programmers. But these days implementers of the spec are both programmers and non-programmers.
Troy Klukewich
Information Architect

From Michael Priestley <mpriestl@ca.ibm.com>
Sent Thu 10/1/2009 8:11 AM
To Joann Hackos <joann.hackos@comtech-serv.com>
Cc DITA TC <dita@lists.oasis-open.org>
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]