Re: [dita] Another request for steps-informal example

[Joann Hackos <joann.hackos@comtech-serv.com>]

Title: Re: [dita] Another request for steps-informal example

Hi Bob,
I think your argument is very well stated. I’m also having problems with authors who don’t want to be “confined” by the semantic rules implied by the element names. I feel that the semantics lead to more thoughtful and disciplined authoring.

I do have an idea about steps-informal however. One of the examples I use in workshops comes from recipes. Recipes are a good potential case for DITA authoring but the syntax of an instruction in a recipe is significantly different from the syntax of an instruction in technical literature (by the way — these are all conventions of our communities of practice).

Here’s a recipe from a recent copy of Sunset Magazine.

<task><title>Argula parmesan salad</title>
<shortdesc>THE VEGETABLE Arugula has a distinctive appealingly peppery flavor. Use just a touch of sweet balsamic vinegar to enhance rather than mask it.</shortdesc>
<taskbody><prereq><sl><li>1 tbsp. plus 2 tsp. red-wine vinegar</li>
                    <li>1 tsp balsamic vinegar</li>
                     ...</sl>
</prereq>
<context><p>Serves 8  Time 15 minutes </p></context> //would be nice to specialize these data items//
<steps-informal><ol>
                    <li>In a bowl, whisk together vinegars, garlic, and olive oil. Add salt and pepper to taste.</li>
                    <li>Put arugula in a large bowl and toss with herbs and dressing. Add parmesan, then toss one more time.</li></ol>
</steps-informal>
</taskbody>
</task>

Incidentally, this recipe is quite short. Sometimes a single step will have 10-15 actions. 

This use of <steps-informal> would allow me to indicate a set of steps, perhaps enabling a specialization of the <ol> to <recipe-steps>. It would allow a different structure than <cmd><info>, allowing for the multiple actions typically described in a recipe “step.” 



I invite comments on this solution. Sorry if there are any mark errors. 
JoAnn


On 2/2/09 11:43 PM, "Bob Thomas" <bob.thomas@tagsmiths.com> wrote:

I do not agree that there is an advantage of using steps-informal instead of steps when the semantics of steps works. Here is why:

• The steps element is semantically more specific than the ol element. Semantically specific markup increases intelligence that is embedded in the markup. Increased intelligence means that more things can be done with the document and that the document can be manipulated with less effort.
• The author is more focused on what the content's intent is for the reader when using the steps/step/cmd/info/... vocabulary than the author would be when using ol/li/p/....
• The semantics of steps discourages the author from munging information types together. For example, the mandatory presence of the cmd element in step strongly suggests that the author ought to use the imperative mood becuase they are giving the reader a command. Contrast this with li which only suggests that a number is going to show up in the output, leaving the author to ramble on what might happen and why if they do this or that.
  

Clearly, a competent, disciplined author will create pretty much the same output in either case. It's just that the writing environment afforded by explicit semantics guides the author into a desirable direction thereby accelerating the writing process and improving consistency across the writing project.

 I am glad that steps-informal is part of 1.2 because it provides a good deal of architectural flexibility. However, it having it there for authoring is not such a good idea. I feel strongly enough about this that I will be advising my clients to use the constraints mechanism to remove steps-informal from their authoring environments. Should they come up with use cases where informal-steps would solve a problem, I will encourage them to look deeper into the semantics of the use cases, and then to specialize informal-steps using those semantics rather than using informal-steps directly.

Bob Thomas
Tagsmiths, LLC <tagsmiths.com>
+1 720 201 8260

---

From: Su-Laine Yeo <su-laine.yeo@justsystems.com>
To: Robert D Anderson <robander@us.ibm.com>; dita <dita@lists.oasis-open.org>
Sent: Monday, February 2, 2009 7:27:07 PM
Subject: RE: [dita] Another request for steps-informal example

Here's how I would explain it:

The <steps-informal> element can be used in the place of either <steps>
or <steps-unordered> to document the actions that the reader should
perform in a task. For example, six actions that the reader must perform
in a particular sequence could be marked up as follows:

<steps>
<step><cmd>Remove the old oil filter.</cmd></step>
<step><cmd>Drain the old oil.</cmd></step>
<step><cmd>Install a new oil filter and gasket.</cmd></step>
<step><cmd>Add new oil to the engine.</cmd></step>
<step><cmd>Check the air filter and replace or clean it.</cmd></step>
<step><cmd>Top up the windshield washer fluid.</cmd></step>
</steps>

Using the <steps-informal> element, the same actions can be documented
as follows:

<steps-informal>
<ol>
<li>Remove the old oil filter.</li>
<li>Drain the old oil. </li>
<li>Install a new oil filter and gasket. </li>
<li>Add new oil to the engine.</li>
<li>Check the air filter and replace or clean it.</li>
<li>Top up the windshield washer fluid.</li>
</ol>
</steps-informal>

The advantage of using <steps-informal> with <ol>, instead of <steps>,
is that compared to <steps>, the <ol> content model is simpler. It also
has more similarities to HTML, making document conversion from HTML
easier.

Su-Laine

-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com]
Sent: Monday, February 02, 2009 11:23 AM
To: dita
Subject: [dita] Another request for steps-informal example


Hello everybody,

Early drafts of DITA 1.2 added a <process> element to task for
describing
procedural task information that does not fit into <steps>. I asked a
couple of times for an example to include in the language specification,
but didn't get one.

Late last year we changed the name from <process> to <steps-informal>,
but
I still don't have an example.

Can anybody on the list provide an example for the <steps-informal>
element? The original proposal does not explain the element beyond what
I've stated above, and does not give an example. I know a number of
people
on the TC feel this element is critical, so I would appreciate it if one
of
those people can provide an example to include in the Language
Specification...

Thanks,

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php