Stage 2 proposal: let steps nest within steps

["Robert D Anderson" <robander@us.ibm.com>]

DITA 2.0 proposed feature #106: Allow <steps> to nest

Allow the <steps> element to nest, in order to address one of our more common authoring pain points, simplify reuse, and reduce overall element count.

Date and version information
Date that this feature proposal was completed

14 March 2018

Champion of the proposal

Robert D. Anderson

Links to any previous versions of the proposal

• Original thread raising the issue 20 July 2017: https://lists.oasis-open.org/archives/dita/201707/msg00037.html
• Discussed 1 August 2017: https://lists.oasis-open.org/archives/dita/201708/msg00004.html

Links to minutes where this proposal was discussed at stage 1 and moved to stage 2

https://lists.oasis-open.org/archives/dita/201803/msg00052.html

Links to e-mail discussion that resulted in new versions of the proposal

N/A

Link to the GitHub issue

https://github.com/oasis-tcs/dita/issues/106

Original requirement or use case
Discussed August 1 2017: The current task structure allows <substeps> to be nested within <steps>, but you cannot nest <steps> within itself or <substeps> within itself, making it impossible to nest any sort of step beyond the second level. We have heard the following requests related to that structure, all suggesting that <steps> should be able to nest within itself:

• I need the ability to nest three levels of steps/sub-steps. The current limitation is arbitrary, with the TC deciding for me that I am supposed to create additional nested tasks. The current limitation is also meaningless because I just insert <ol> inside of the <info> portion of the step.
• I am frustrated at having to insert different elements for the same type of content. There is no semantic difference between <steps> and <substeps> – the ability to nest one task within another means that steps in one context are sub-steps in another.
• I need to reuse a step in one context as a sub-step in another. I cannot, because the difference in elements makes it impossible to establish content reference relationships with @conref or @conkeyref between a step and a sub-step (even tough as established above, a step in one context is often a sub-step in another context).
• My sub-steps don't have a specified order, but the current markup only allows me to use ordered <substeps> even though I can have unordered steps at the task level.

Use cases
As indicated by the use cases / requirements above:

• Those who already create 3 levels of lists in a task would like to use proper markup (<steps> within <steps> within <steps>, rather than <ol> within <info> within <substeps> within <steps>).
• Those who need to reuse a <substep> from one task as a <step> in another (or vice versa) would like to do so as a single content reference (rather than having to use cut/paste or having to reference each individual sub-element).
• Those who want to use sub-steps without specifying an order would like to do so without resorting to <ul> inside of <info>.

New terminology

N/A

Proposed solution

1. Allow <steps> and <steps-unordered> to nest within <step> (after the command, as part of the 0-to-many group of elements including <choices>, <info>, and other components).
2. Remove the <substeps> and <substep> elements, which are no longer necessary.

Benefits
Who will benefit from this feature?

All authors using the task model.

What is the expected benefit?

• Reduced frustration
• Easier reuse
• Ability to use appropriate markup for all steps in a task

How many people probably will make use of this feature?

Many users of the task document type.

How much of a positive impact is expected for the users who will make use of the feature?

Probably a medium impact; this is a long-standing issue that regularly causes small annoyances, so fixing it will remove a small but constant source of irritation.

Technical requirements
Adding new elements or attributes

Adding an element
This is not exactly adding a new element, but adding an existing element to a new context. The definitions of the <steps> element and <steps-unordered> elements do not change.

Removing elements or attributes

Removing an element
The <substeps> and <substep> elements will be removed from the task specialization.

Processing impact

There should be little processing impact; tools with special processing for steps/sub-steps will need to handle the possibility of 3 or more levels of nesting, while tools that already rely on fallback processing to ordered / unordered lists will see no impact.

Overall usability

No additional setup is necessary; based on feedback, authors will consider the revised model more usable than the existing one, so this will be a slight improvement.

Backwards compatibility
Was this change previously announced in an earlier version of DITA?

No

Removing or renaming an element that was shipped in DITA 1.3?

Yes, removing <substeps> and <substep> from the task specialization.

Changing a content model by removing something that was previously allowed, or by requiring something that was not?

Yes; the change removes <substeps> from the content model of <step>

Migration plan
Might any existing documents need to be migrated?

Yes, any task that uses <substeps>. If there is a script to migrate files, this will make an easy addition to that script. Otherwise, this should be easily accomplished with a search/replace operation across files:
1. Replace <substep with <step
2. Replace </substep with </step

Though unlikely, any existing specializations of <substeps> outside of OASIS may require additional migration, but this might also be handled with relevant updates in the specialization module (leaving documents untouched). For example, if there is a specialization of <substeps> called <littleSteps>, the documents will not need migration. Instead, the declaration of the element's @class attribute will need to change so that the ancestry task/substeps becomes task/steps. The same change would be necessary for specializations of <substep>.

Might any existing processors or implementations need to change their expectations?

If a processor does something special with <substeps> that behavior will need to be updated to work with <steps> inside of <steps>, and will also need to ensure it can handle additional levels of nesting.

Might any existing specialization or constraint modules need to be migrated?

Potentially:
• If a specialization module specializes <substeps>, the element ancestry for that new element will need to be updated so that it includes task/steps rather than task/substeps (and an equivalent update for specializations of <substep>).
• If a specialization or constraint module explicitly allows or references either <substeps> or <substep>, that module will need to remove that reference.

Costs
Outline the impact (time and effort) of the feature on the following groups:
Maintainers of the grammar files

Small cost of removing 2 element definitions and updating the content model of <step>

Editors of the DITA specification

• No new topics
• Need to remove 2 element reference topics

Vendors of tools

Low cost (if any) as described above.

DITA community-at-large

This will simplify the language (good impact!) but will result in an additional migration item for many task topics. Under the assumption that all topics will require some minimal migration regardless, this will present very little additional cost.

Producing migration instructions or tools

Migration instructions are simple, replacing 2 elements with 2 already known and similarly named elements. If tools already exist to migrate documents this should be added (at very low cost), but I do not anticipate tools explicitly for this.

Examples
Figure 1. Before/after of basic structure 
Current markup for 3-level steps:
<steps>
  <step><cmd>Major command</cmd>
    <substeps>
      <substep><cmd>Sub-command</cmd>
        <info>
          <ol>
            <li>Long way to go, and is this still a command</li>
          </ol>
        </info>
      </substep>
    </substeps>
  </step>
</steps>
New markup for 3-level steps:
<steps>
  <step><cmd>Major command</cmd>
    <steps>
      <step><cmd>Sub-command</cmd>
        <steps>
          <step><cmd>Long way to go, and is this still a command</cmd></step>
        </steps>
      </step>
    </steps>
  </step>
</steps>
Figure 2. Example with unordered sub-steps 
Currently any unordered sub-steps must establish an order (using the ordered <substeps>), or must be created with alternate markup:
<steps>
  <step><cmd>This command has some components</cmd>
    <info>
      <ul>
        <li>As you can see,</li>
        <li>the order is not important</li>
        <li>But I'd like to mark them up as steps / commands</li>
      </ul>
    </info>
  </step>
</steps>
With unordered steps allowed within a <step>, the correct markup can be used:
<steps>
  <step><cmd>This command has some components</cmd>
    <steps-unordered>
      <step><cmd>As you can see,</cmd></step>
      <step><cmd>the order is not important</cmd></step>
      <step><cmd>But I'd like to mark them up as steps / commands</cmd></step>
    </steps-unordered>
  </step>
</steps>
Figure 3. Reuse model 
Currently the only ways to reuse a step from one task as a sub-step in another context are to either cut and paste, or to use content references on every component:
in topicA.dita:
<step id="stepZ">
  <cmd id="stepZcmd">command...</cmd>
  <stepxmp id="stepZxmp">example...</stepxmp>
  <info id="stepZinfo">more info...</info>
  <stepresult id="stepZresult">what you end up with...</stepresult>
</step>

in topicB.dita:
<substep>
  <cmd conkeyref="topicA/stepZcmd"/>
  <stepxmp conkeyref="topicA/stepZxmp"/>
  <info conkeyref="topicA/stepZinfo"/>
  <stepresult conkeyref="topicA/stepZresult"/>
</subtep>
This is ugly, difficult to maintain, and content will be broken if the original stepZ adds or removes markup (especially if it adds something like <choices> that is not even available in a sub-step). Allowing steps to nest results in the following change; the reuse element still requires the empty <cmd> as with any content reference on an element with required children:
in topicA.dita:
<step id="stepZ">
  <cmd id="stepZcmd">command...</cmd>
  <stepxmp id="stepZxmp">example...</stepxmp>
  <info id="stepZinfo">more info...</info>
  <stepresult id="stepZresult">what you end up with...</stepresult>
</step>

in topicB.dita:
<step conkeyref="topicA/stepZ"><cmd/></step>

Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA