Adjust lead-in sentences

[bergerhoffer]

In DITA, we won't be able to have lead-in sentences to prerequisites or procedures. Right now, our guidance for lead-in sentences is to avoid them, but you can add them if you have good reason to.

We probably need to adjust this guidance to not allow lead-in sentences at all.

[jeana-redhat]

Seems like one of those cases where the guidance might be better as "work it into the intro" (or another valid place)

[chloeguling]

I wanted to clarify something about lead-in sentences in DITA. From what I’ve read and tested, DITA doesn’t actually prohibit them. In a task topic, you can use the element before if you need to set up the procedure, and in you can also include a short explanatory sentence. For example:

<prereq>
  Here's an example lead-in sentence:
  <ul>
    <li>Download permissions</li>
    <li>Network access</li>
  </ul>
</prereq>

I also somewhat disagree with Red Hat's take to not use lead-in sentences. They are typically considered good practice in the tech writing industry, and they also help with accessibility.

[bergerhoffer]

CC @jhradilek to weigh in

[jeana-redhat]

I am interested in seeing an example good use of these. I have never seen one in our docs that wasn't a restatement of the title and/or introduction.

Typically something like this:

= Installing the whats-it plugin

To install the whats-it plugin, you create a configuration file with the required details and apply it to your cluster.

.Procedure

To install the whats-it plugin, complete the following steps:

. First step.

. Second step.

[jhradilek]

It is not a problem for <prereq> or any other part a DITA task with the notable exception of <steps> and <steps-unordered>. For context, we are talking about conversion from AsciiDoc where the .Procedure block title is used to identify what part should be converted to it, and converts the ordered or unordered list to <steps> or <steps-unordered> respectively. In this situation, a leading sentence has nowhere to go and should be part of the <context> element that precedes it.

The problem in AsciiDoc and our current modular documentation guidelines is that we place Prerequisites after the context whereas DITA places them above it. That makes it tricky to produce a leading sentence if .Prerequisites are present as well.

I am aware of the existence of <stepsection>, but converting <ol>/<ul> and <li> to a correctly alternating sequence of <step>, <cmd>, <info>, <substep>, and <stepxmp> is already very complex. Converting arbitrary content beyond a list that can be directly mapped to steps is not worth the effort.

Example AsciiDoc code

:_mod-docs-content-type: PROCEDURE

= Topic title

Here is a leading sentence:

.Procedure

. Step one.
. Step two.

Example DITA conversion

<?xml version="1.0"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="test">
  <title>Topic title</title>
  <taskbody>
    <context>
      <p>Here is a leading sentence:</p>
    </context>
    <steps>
      <step>
        <cmd>Step one.</cmd>
      </step>
      <step>
        <cmd>Step two.</cmd>
      </step>
    </steps>
  </taskbody>
</task>

[jhradilek]

To clarify, there are no inherent restrictions to having leading sentences in .Prerequisits, Verification/.Result, .Troubleshooting, or .Next steps. In fact, I personally believe they are beneficial. For a procedure itself, the <context> element should do enough to introduce the steps.

[IngridT1]

I don't see that there is an action to take on this Issue after all, @jhradilek and @bergerhoffer . Am I missing something?

[jhradilek]

The one possible improvement I can think of is to this text:

A lead-in sentence in this context is the text that directly follows a Prerequisites or Procedure heading in a task-based module. It is distinct from the module abstract, which describes the goals of the user for the module.

Do not use a lead-in sentence in the Prerequisites or Procedure sections of a module unless it is necessary to aid navigation or add clarity.

The first paragraph is correct and clearly explains that a leading sentence is the text that follows the heading. The second sentence is potentially problematic, because it implies that people can break this rule when it suits them. Doing so with Prerequisites is acceptable, but if they do that with Procedure, they will create a problem for conversion.