Loading ...
Sorry, an error occurred while loading the content.
 

Re: [dita-users] task element usage debate

Expand Messages
  • Yves Barbion
    Hi Ben According to the DITA Language Spec, the parameter list ( ) element contains a list of terms and definitions that describes the parameters in an
    Message 1 of 10 , Aug 20, 2013
      Hi Ben

      According to the DITA Language Spec, "the parameter list (<parml>) element contains a list of terms and definitions that describes the parameters in an application programming interface. This is a special kind of definition list that is designed for documenting programming parameters."

      http://docs.oasis-open.org/dita/v1.2/os/spec/langref/parml.html#parml

      When I read your text, I don't see "terms and definitions" and I also don't think we're dealing with an application programming interface here.

      Therefore, I'd structure your text like this:


            <steps>
                  <step>
                      <cmd>To replicate the protection domain to one or more remote sites, click the
                              <uicontrol>Replicate action</uicontrol>  link.</cmd>
                      <stepresult>
                          <p>The <wintitle>Replicate Protection Domain</wintitle> dialog box appears.</p>
                      </stepresult>
                  </step>
                  <step>
                      <cmd>Do the following in the indicated fields:</cmd>
                      <info>
                          <ul>
                              <li><uicontrol>Remote sites</uicontrol>: Check the box(es) of the target
                                  remote site(s).</li>
                              <li><uicontrol>Replication start time</uicontrol>: Select the start time
                                  from the pull-down list. Choices range from now to 48 hours from
                                  now.</li>
                              <li><uicontrol>Retention time</uicontrol>: Select the retention interval
                                  (how long the snapshot is saved on the remote sites) from the pull-down
                                  list. Choices range from one day to indefinitely.</li>
                          </ul>
                      </info>
                  </step>
                  <step>
                      <cmd>Click <uicontrol>Save</uicontrol>.</cmd>
                  </step>
              </steps>

      I wouldn't use choices or choicetable here because the options given are not mutually exclusive.



      Cheers

      --
      Yves Barbion
      www.scripto.nu
    • homernbender
      I d use steps or substeps. Without knowing your content, what you ve currently shown using substeps could be its own task instead of a step with some substeps
      Message 2 of 10 , Aug 21, 2013
        I'd use steps or substeps. Without knowing your content, what you've currently shown using substeps could be its own task instead of a step with some substeps in a larger task. Splitting it out into a separate task could make it more reusable and you could still present it as part of a larger workflow using related links or chunking. But like I said, I don't know your content so it's tough to say whether that would be a better choice.

        This is how I would write it:

        <taskbody>
        <steps>
        <step>
        <cmd>To replicate the protection domain to one or more remote sites, click <uicontrol>Replicate</uicontrol>.</cmd>
        <stepresult><wintitle>Replicate Protection Domain</wintitle> is displayed.</stepresult>
        </step>
        <step>
        <cmd>For <uicontrol>Remote sites</uicontrol>, select the target remote sites you want to apply domain protection to.</cmd>
        </step>
        <step>
        <cmd>For <uicontrol>Replication start time</uicontrol>, select the start time.</cmd>
        <info>Choices range from the current time to 48 hours from the current time.</info>
        </step>
        <step>
        <cmd>For <uicontrol>Retention time</uicontrol>, select the retention interval to indicate how long the snapshot is saved on the remote sites.</cmd>
        <info>Choices range from one day to indefinitely.</info>
        </step>
        <step>
        <cmd>Click <uicontrol>Save</uicontrol>.</cmd>
        </step>
        </steps>
        </taskbody>


        --- In dita-users@yahoogroups.com, "Ben Colborn" <bcolborn@...> wrote:
        >
        > We're having a debate in my group about some element usage. In our
        > product there are many cases where a step is to fill out a form then
        > submit. One writer thinks that filling in each field should be a
        > substep, while another thinks that a parameter list would be more
        > appropriate. See below for examples. (I'll withhold which side I'm on).
        > I checked "DITA Best Practices", the "Microsoft Manual of Style", and
        > Developing Quality Technical Information" from IBM. None of them discuss
        > this sort of structure.
        > Which usage do you think is more semantically appropriate?
        > Substep example:
        > 1. To replicate the protection domain to one or more remote sites,
        > click the Replicate action link.The Replicate Protection Domain dialog
        > box appears. Do the following in the indicated fields:
        >
        > 1. Remote sites: Check the box(es) of the target remote site(s).
        > 2. Replication start time: Select the start time from the pull-down
        > list. Choices range from now to 48 hours from now.
        > 3. Retention time: Select the retention interval (how long the
        > snapshot is saved on the remote sites) from the pull-down list. Choices
        > range from one day to indefinitely.
        > 4. When all the field entries are correct, click the Save button.
        > Parml example:
        > 1. To replicate the protection domain to one or more remote sites,
        > click the Replicate action link.The Replicate Protection Domain dialog
        > box appears. Do the following in the indicated fields:Remote sitesCheck
        > the box(es) of the target remote site(s).Replication start timeSelect
        > the start time from the pull-down list. Choices range from now to 48
        > hours from now.Retention timeSelect the retention interval (how long the
        > snapshot is saved on the remote sites) from the pull-down list. Choices
        > range from one day to indefinitely.When all the field entries are
        > correct, click the Save button.
        >
      • Leigh White
        I would create the field/control list as a separate reference topic with the fields either in a table or a definition list. I would then conref the list into
        Message 3 of 10 , Aug 21, 2013
          I would create the field/control list as a separate reference topic with the fields either in a table or a definition list. I would then conref the list into the task at the appropriate spot. I would take this approach because it's possible that many different tasks can take place on this same window, using the same fields. Being able to conref the field descriptions into multiple tasks is both a time-saver and reduces the opportunity for the definitions of a single field in, say, 10 different tasks to fall out of sync with one other.

          In the event that

          1. the tasks that take place on the same window all use the same fields but in different ways, and there is no way you can write one set of field descriptions that covers all the cases
          OR
          2. some tasks on the same window use only some of the fields and you don't want to mention fields that aren't used in that particular task

          you could still maintain all of the field variations separately as conref targets and conref them in individually in the appropriate tasks. This approach gives you the advantage of at least being able to see the variations on a field all together in one place. It might even help you be able to point out any coding or terminology inconsistencies to the development team.

          My two cents :-)
          Leigh

          --- In dita-users@yahoogroups.com, "Ben Colborn" <bcolborn@...> wrote:
          >
          > We're having a debate in my group about some element usage. In our
          > product there are many cases where a step is to fill out a form then
          > submit. One writer thinks that filling in each field should be a
          > substep, while another thinks that a parameter list would be more
          > appropriate. See below for examples. (I'll withhold which side I'm on).
          > I checked "DITA Best Practices", the "Microsoft Manual of Style", and
          > Developing Quality Technical Information" from IBM. None of them discuss
          > this sort of structure.
          > Which usage do you think is more semantically appropriate?
          > Substep example:
          > 1. To replicate the protection domain to one or more remote sites,
          > click the Replicate action link.The Replicate Protection Domain dialog
          > box appears. Do the following in the indicated fields:
          >
          > 1. Remote sites: Check the box(es) of the target remote site(s).
          > 2. Replication start time: Select the start time from the pull-down
          > list. Choices range from now to 48 hours from now.
          > 3. Retention time: Select the retention interval (how long the
          > snapshot is saved on the remote sites) from the pull-down list. Choices
          > range from one day to indefinitely.
          > 4. When all the field entries are correct, click the Save button.
          > Parml example:
          > 1. To replicate the protection domain to one or more remote sites,
          > click the Replicate action link.The Replicate Protection Domain dialog
          > box appears. Do the following in the indicated fields:Remote sitesCheck
          > the box(es) of the target remote site(s).Replication start timeSelect
          > the start time from the pull-down list. Choices range from now to 48
          > hours from now.Retention timeSelect the retention interval (how long the
          > snapshot is saved on the remote sites) from the pull-down list. Choices
          > range from one day to indefinitely.When all the field entries are
          > correct, click the Save button.
          >
        • Ron Wheeler
          Very clever way to handle the actual text. +1 Ron ... -- Ron Wheeler President Artifact Software Inc email: rwheeler@artifact-software.com skype:
          Message 4 of 10 , Aug 21, 2013
            Very clever way to handle the actual text.
            +1

            Ron
            On 21/08/2013 3:41 PM, Leigh White wrote:
            > I would create the field/control list as a separate reference topic with the fields either in a table or a definition list. I would then conref the list into the task at the appropriate spot. I would take this approach because it's possible that many different tasks can take place on this same window, using the same fields. Being able to conref the field descriptions into multiple tasks is both a time-saver and reduces the opportunity for the definitions of a single field in, say, 10 different tasks to fall out of sync with one other.
            >
            > In the event that
            >
            > 1. the tasks that take place on the same window all use the same fields but in different ways, and there is no way you can write one set of field descriptions that covers all the cases
            > OR
            > 2. some tasks on the same window use only some of the fields and you don't want to mention fields that aren't used in that particular task
            >
            > you could still maintain all of the field variations separately as conref targets and conref them in individually in the appropriate tasks. This approach gives you the advantage of at least being able to see the variations on a field all together in one place. It might even help you be able to point out any coding or terminology inconsistencies to the development team.
            >
            > My two cents :-)
            > Leigh
            >
            > --- In dita-users@yahoogroups.com, "Ben Colborn" <bcolborn@...> wrote:
            >> We're having a debate in my group about some element usage. In our
            >> product there are many cases where a step is to fill out a form then
            >> submit. One writer thinks that filling in each field should be a
            >> substep, while another thinks that a parameter list would be more
            >> appropriate. See below for examples. (I'll withhold which side I'm on).
            >> I checked "DITA Best Practices", the "Microsoft Manual of Style", and
            >> Developing Quality Technical Information" from IBM. None of them discuss
            >> this sort of structure.
            >> Which usage do you think is more semantically appropriate?
            >> Substep example:
            >> 1. To replicate the protection domain to one or more remote sites,
            >> click the Replicate action link.The Replicate Protection Domain dialog
            >> box appears. Do the following in the indicated fields:
            >>
            >> 1. Remote sites: Check the box(es) of the target remote site(s).
            >> 2. Replication start time: Select the start time from the pull-down
            >> list. Choices range from now to 48 hours from now.
            >> 3. Retention time: Select the retention interval (how long the
            >> snapshot is saved on the remote sites) from the pull-down list. Choices
            >> range from one day to indefinitely.
            >> 4. When all the field entries are correct, click the Save button.
            >> Parml example:
            >> 1. To replicate the protection domain to one or more remote sites,
            >> click the Replicate action link.The Replicate Protection Domain dialog
            >> box appears. Do the following in the indicated fields:Remote sitesCheck
            >> the box(es) of the target remote site(s).Replication start timeSelect
            >> the start time from the pull-down list. Choices range from now to 48
            >> hours from now.Retention timeSelect the retention interval (how long the
            >> snapshot is saved on the remote sites) from the pull-down list. Choices
            >> range from one day to indefinitely.When all the field entries are
            >> correct, click the Save button.
            >>
            >
            >
            >
            > ------------------------------------
            >
            > Yahoo! Groups Links
            >
            >
            >
            >


            --
            Ron Wheeler
            President
            Artifact Software Inc
            email: rwheeler@...
            skype: ronaldmwheeler
            phone: 866-970-2435, ext 102
          Your message has been successfully submitted and would be delivered to recipients shortly.