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

[Eliot Kimber <ekimber@reallysi.com>]

The issues seem to revolve around these key questions:

- Should a single task allow multiple <steps> elements? If it does, how 
should content specific to a given <steps> element be bound to it (e.g., 
<context>)? Other than <section>, DITA 1.2 currently provides no generic 
wrapper element that could be used to bind <context> and <steps> and 
relying on sequences of pairs is not workable since the resulting 
content model would be (context?, steps)+ which is functionally 
equivalent to (context | steps)+ which doesn't really impose the desired 
constraint. Putting an element within <steps> as some sort of intro 
won't work without extending the current base list model to allow it 
(that is, anything within <steps> must be specialization of <li> as DITA 
1.1 is defined).

- Should there be a way to group steps within a single <steps> element 
that is not substeps within steps? 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). The current content model requires that this content be 
either outside of <steps> entirely or bound within a specific step 
within the procedure, neither of which are completely satisfactory.  The 
problem here is that, again, the base list model would need to be 
extended to provide a grouping element for list items. Making that 
change would require a separate proposal and might itself be controversial.

With regard to the specifics in Alan's note, my feeling is:

For the content model of <step>:

- Allowing note at start of step is absolutely essential for all the 
reasons cited (e.g., by the Machine Industry SC)

- 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. I don't think that concerns about the base content model being 
too open are appropriate in general for DITA because of its inherent 
need for generality, which will only increase over time and I certainly 
don't think that such concerns outweigh the potential utility of 
<itemgroup> in this case. But since there's already <info> I don't see 
the need for <itemgroup> to be that compelling either.

- As discussed on the call, I don't see the value in allowing <cmd> to 
be optional--it's not clear what a step with no command would be in that 
case. It seems to me that having a command is the essential 
distinguisher between steps and ordered list items. (That and being 
explicitly part of a task.)

For the content model of <steps>:

- See discussion above. In addition, I agree with Michael P. that 
allowing multiple <steps> seems to be fundamentally at odds with the 
general DITA principle of modularity and using subtopics. In addition, 
groups of related steps can be organized as a sequence of steps with 
substeps if the requirement is to have the whole lot followed by the 
usual task post-steps stuff.

One issue I have run into in trying to do more complicated procedures is 
the unavoidable need to have xrefs from high-level process descriptions 
to individual task topics that describe each component process. It would 
be nice if those links could be defined and managed at the map level but 
I can't think of a way it could be done with current mechanisms 
(although keyref would probably help).

It may be that complex tasks are simply a case where embedded 
topic-to-topic links are unavoidable, but it's something I certainly 
need to think about more. But I don't think that allowing multiple 
<steps> would be the right answer in any case.

I know that there's a concern that there is a lot of legacy content that 
just won't map easily to a single-<steps> model but I think that's just 
an unavoidable cost of moving to DITA.

For the content model of taskbody:

- I would definitely like to be able to choose the order of things 
before and after <steps> (e.g., put context before prereqs). Alan's 
option 2 seems the best but the more general option 3 also appeals 
simply because it is the least constrained.

- 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? Is it 
simply to allow tasks that are described in unstructured prose rather 
than as a sequence of steps? If so, I would prefer an alternative to 
<steps> that then allows arbitrary text, e.g. <process-description> or 
something. Otherwise there seems to be too much risk of <ol> or <ul> 
being used when <steps> or <steps-unordered> should be used. That is, 
containing <steps> is the essential distinguisher of task from topic.

- I think allowing <section> is probably essential--it adds options for 
specialization (e.g., as typified the Machine Industry task 
specialization proposal) without diluting the essential task nature.

Thus I think I would prefer a content model for taskbody more like this:

((context |
   prereq |
   section)*,
  (steps |
   steps-unordered |
   process-description),
  (result |
   example |
   postreq |
   section)*
)

Where <process-description> is a specialization of <section> with the 
same content model as <section>.

With this content model, the minimum required taskbody would be a single 
<process-description> or <steps> or <steps-unordered> but much richer 
models before and after the process description/definition would be allowed.

Cheers,

Eliot

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com