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
