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] Content model options for #12011 - Generic Task Type

I'm inclined to think that if a task has more than one set of steps, it's not a task.

That said, the case of a single set of steps with an interspersed discussion element is something I've seen before - I don't know whether it's good style, but it's still a single set of steps, just interrupted.

Rather than create alternates at the <steps> level, could we preserve the requirement for a single set of <steps> but allow more freedom within it? In other words, instead of adding <ol> and <ul> as peers of <steps> and <steps-unordered>, just allow <li> as a peer of <step>. And add a new specialization of <li> - <discussion> - that has override behavior to appear without numbering or indenting (ie it interrupts the flow of the task but not the numbering of the steps).

I can also see the point of allowing <note> and <itemgroup> into the content model of <step>. Although in the case of itemgroup I can't think of any case where <info> wouldn't do the job, I accept that there are some things I probably haven't thought of, and <itemgroup> is certainly even more generic than <info>. And this isn't an issue that strikes at the identity of the task infotype, like allowing multiple sets of steps would (for me).

That leaves the question of what kinds of generic containers to allow before and after <steps>. I'd love to just make <section> available in both places, and it's unfortunate XML that I can't without sacrificing control over the number of <steps> elements. Perhaps we could address the problem by allowing multiple <prereq> and <context> elements before <steps>, and adding multiple <section>, <postreq>, and <example> elements after <steps>?

 (prereq|context)*, steps?, (postreq|section|example)*


I should run this by some IBM editors and see how much gnashing of teeth results. Even though the point of making task more generic is to allow more specialization, the other point of task is to hold the gates against bad writing practices. The more we punt to constraints, the less useful the base task module is on its own. Otherwise we could just use the task module to declare all the new elements, and a constraints module to declare the actual content models. Maybe that will become our ultimate direction - the complete separation of semantics from structure - but I'd rather save a major new design direction like that for 2.0 - and in the meantime keep the task module usable as an actual declaration of task structure, not just a bucket of elements.

Michael Priestley
Lead IBM DITA Architect


11/27/2007 08:32 PM

Eliot Kimber <ekimber@reallysi.com>
Re: [dita] Content model options for #12011 - Generic Task Type

Eliot Kimber <ekimber@reallysi.com> wrote on 28/11/2007 04:53:38 AM:
> Key use cases here are tutorials and
> troubleshooting, where you want to have some discussion that encompasses
> all the foregoing or all following steps in a group (e.g., talking about
> where you've gotten after 4 steps of a 6-step atomic process within a
> tutorial).

(I just pulled that bit out because that's the one use case I have which <task> doesn't currently give me. Consider that sentence the context of my reply.)

> - Should a single task allow multiple <steps> elements? [...]
> - Should there be a way to group steps within a single <steps> element
> that is not substeps within steps? [...]

As Eliot said, both of these could satisfy my use case (I do the former as a specialization of <topic>).  The latter is probably cleaner, though it requires more architectural upheaval.

I'd been hoping to avoid the philosophical question of "what is a task?" but perhaps I can't.  Are my worked-examples-with-interspersed-discussion tasks?  I think they are, but I am prepared to admit that I am looking at them through legacy-topic-coloured glasses.  They might have been refactorable as straight tasks, probably with some splitting.

> With regard to the specifics in Alan's note, my feeling is:
> For the content model of <step>:
> - I see the value of allowing <itemgroup> to enable arbitrary
> specialization that is not based on <info>. However, I would be OK with
> not allowing <itemgroup> if we agree that <info> is sufficiently
> generic.

Agreed, though I do note that we don't have a perfect track record in forecasting how generic is "sufficiently generic".  Read on...

> For the content model of taskbody:
> - I don't understand the value of allowing <ol> or <ul> in place of
> <steps> in any of these options. What is the motivation there?

That idea was mine.  Like <itemgroup> in <step>, it is intended as a specialization extension point for things that are neither <steps> nor <steps-unordered>.  (At the time it was acting as a surrogate for <simple-steps> or whatever it has morphed into.)  Like <itemgroup>, the plan was for all shell DTDs to restrict the unspecialized version away.  (Back to "sufficiently generic" again...)

I assume that there will be two normative restrictions of <task>: Strict <task>, which is a replica of DITA 1.1 <task>, and Loose <task>, which is just loose enough to cater to everyone's new requirements.  Importantly, Loose <task> is *still a restriction* of the true content model of <task>.  Arguing the content model of general <task> based on the requirements of Loose <task> is certain to underestimate the amount of genericity required.  For that, we need to ask "what will specializers need from a generic <task>?"  That's my argument for <itemgroup> and <ol> and <ul> (and also for Alan's <taskbody> model #3).  I hope that <itemgroup> in <step> is uncontroversial, and the fact that people are questioning even that it's needed I take as a sign that this is exactly the kind of unobtrusive thing that specializers want.  <ul> and <ol> in <taskbody> I expect to be more controversial.  Good; let's hash out exactly what constitutes the most abstract and generic possible task, and then restrict it for Strict <task> and Loose <task>.  If specializers want something more generic than <task>, then it's time to fall back to <topic>.  

There might be an argument for a topic type that goes between <topic> and <task> in the inheritance tree (perhaps <procedure>), but I don't want to cloud the issue at hand, so I won't elaborate here.

Deborah Pickett
Information Architect, Moldflow Pty Ltd, Melbourne

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