[publican-list] [Bug 687894] rendering of steps inside stepalternatives

[bugzilla at redhat.com]

Please do not reply directly to this email. All additional
comments should be made in the comments box of this bug.


https://bugzilla.redhat.com/show_bug.cgi?id=687894

--- Comment #9 from Eva Kopalova <ekopalov at redhat.com> 2012-04-26 10:17:15 EDT ---
Hi Brian,
I would like to note:

> Meta thought: stepalternatives should be an authorial flag to re-consider the
> procedure’s basic construction.

If I am using stepalternatives (in this case), I am actually going out of my
way to explain to the user things that are not really within the scope of the
guide in this case:
I could have written: "Stop the httpd daemon." and not provide the exact
commands for individual rhel versions; this would imply I should
reference rhel documentation on how to stop a service.
What I was trying to achieve (and am trying to achieve with
stepalternatives) is to prevent the user from having to go to another
resource and "click around" in the wikipedia style to achieve a single thing:
As stated in the DocBook Guide:

The |stepalternatives|
<http://docbook.org/tdg/en/html/stepalternatives.html> element was added
to support the semantics of alternative steps: perform exactly one of
the following steps. The reader is presumably given some criteria for
deciding which one to choose, but the significant difference is that
only one of the steps is performed.

If we claim that stepalternatives is not correct practise, then the next thing
I would like propose is to pick 40 elements from DocBook and forget about the
rest... and there goes DITA and Mallard. Why are we still using DocBook then?
>
> That aside, assuming stepalternatives are the best option in a given procedure,
> having them delineated by a distinguishable mark (eg a letter) does make it
> possible to reference the particular stepalternative elsewhere in the
> procedure.† This is potentially more useful to a reader than undistinguishable
> dingbats.

I am not aware of any use case when I would reference a stepalternatives
element:
if I were in need of doing that, I would definitely not use the
stepalternatives tag but split the procedure as you did further below. If
referencing then referencing the parent step.

>
>
> † This brings the meta thought above back into play however: if you’re
> referencing earlier stepalternatives later in a procedure, my reflexive thought
> is the entire procedure needs re-structuring.
>
> The sample structure given in comment #1 above, for example, could be
> re-structured thus to avoid stepalternatives:
>
> <procedure
> id="proc-Stopping_HTTP_on_Red_Hat_Enterprise_Linux_5_and_6-Linux-RPM">
>   <title>Stopping HTTP on Red Hat Enterprise Linux 5 and 6</title>
>    <para>
>    Follow this procedure to stop<classname>httpd</classname>:
>    </para>
>
>     <step>
>      <para>
>       At the shell prompt, become the root user.
>      </para>
>     </step>
>
>     <step>
>      <para>
>      Run the following<command>stop</command>  command:
>      </para>
>     </step>
> </procedure>
>
> <procedure id="proc-Stopping_HTTP_on_Red_Hat_Enterprise_Linux_4-Linux-RPM">
>   <title>Stopping HTTP on Red Hat Enterprise Linux 4</title>
>    <para>
>    Follow this procedure to stop<classname>httpd</classname>:
>    </para>
>
>     <step>
>      <para>
>       At the shell prompt, become the root user.
>      </para>
>     </step>
>
>     <step>
>      <para>
>      Run the following<command>stop</command>  command:
>      </para>
>     </step>
> </procedure>
>
> The above is longer but forks the reader’s attention before they begin
> following any steps in the procedure at all. This reduces the likelihood of
> error on the reader’s part considerably.

I really think that this is too atomic: there is only one step that is
different for individual rhel versions.
Also, please, consider that I am actually going out of my way on this
occasion and explaining to the user things I don't really have to.
If I were writing about how to stop a daemon, I would definitely agree
that it is good practise to split this in two procedures; however, the
procedures would not appear in one guide anyway and therefore make no sense at
all.

I also would like to add Stephen's (swadeley) comment, which covers another use
case for stepalternatives:
"As I understand it, step alternatives would follow after a question: Do You
want tea or coffee?
Why would you send someone directly to one of the alternatives? You either send
them to the question or head of the decision tree so they can make an informed
choice or just copy the bit that says 'Press this button for coffee'. Sending
them to the middle of a list of choices when you don't want them to have a
choice is perverse."

-- 
Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.