Re: [dita] Content model options for #12011 - Generic Task Type

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

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>?

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

steps/steps-unordered:
(step|li|discussion)*

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

Deborah_Pickett@moldflow.com

11/27/2007 08:32 PM

To	Eliot Kimber <ekimber@reallysi.com>
cc	dita@lists.oasis-open.org
Subject	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
Deborah_Pickett@moldflow.com