[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Another request for steps-informal example
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:
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.
- 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.
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]