From: Erik Hennum [mailto:ehennum@us.ibm.com]
Sent: September 23, 2004 5:33 PM
To: France Baril
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] Containers for steps and other elements!?
Hi, France:
I'm wondering if the issue is not so much containment
but, instead, conref to multiple items. That is, having a placeholder in the
referencing context that is replaced with multiple items from the referenced
context.
If so, the referencing context would need to identify the
start and end targets in the referenced context. Also, you'd want to make sure
that the referencing context can accept multiple items. One approach would be
to have separate placeholders for the start target and end target, as
in:
<!-- referenced topic -->
<steps>
...
<step
id="startStepID">...</step>
<step>...</step>
<step>...</step>
<step
id="endStepID">...</step>
...
</steps>
<!--
referencing topic -->
<steps>
...
<step
conrefstart="topic.xml#topicID/startStepID"/>
<step
conrefend="endStepID"/>
...
</steps>
If adjacent start
and end placholders are allowed in the context, more than one replacement will
be valid. There are still issues, of course. Does each item have to have the
same element type? What if the referencing context allows a fixed number of
items in the context and the referenced context has more items?
If we
introduce a universal grouping element to contain a list for referencing, the
conref would no longer guarantee that the replacement is valid in context.
We'd also have semantically neutral containers everywhere.
It's a good
issue, but I'd suggest that we take it up after DITA 1.0. All the more reason
to move quickly on DITA 1.0 so we can start improving the base.
One
possible interim workaround would be to model the reused steps as substeps and
conref the step. Or, if the steps are large enough, model each group of steps
as a separate subordinate task topic and use a map to reuse a subtask under
several different container topics.
Hoping that's
useful,
Erik Hennum
ehennum@us.ibm.com
"France Baril"
<France.Baril@ixiasoft.com>
09/23/2004 11:17 AM |
|
Hi, as my project evolve I seem to get into very specific issues.
I'm not sure we're at this level of details yet, but here it is…
I have mutliple tasks that use many of the same steps. Somehow, it would be very useful to be able to reuse not an element, but a group of elements. I'm thinking of containers for elements. Here is an example (note this is a quick unrealistic translation of French content) where I am documenting an application in which there are many ways of doing the same thing, so depending on where you start from and what your goal is as a user, the first steps differ.
Note: The hypothesis is that I am not using the standard dita dtd in which a step may contain substeps and not steps; my step elements may contain other "steps/step" levels.
Task1: how to share a news monitoring folder with other
users
...
Steps
Step: Click Modify Folder
… Would like container (id=SubSetSharingOptions)
Step: In section Sharing, select
Yes.
Step: In section User
groups, check the groups to which you want to grant access.
… End container
Step: Click OK
Task2: how to configure email alerts when new news
documents are added to the news monitoring folder.
...
Steps (id=ConfigureEmailAlerts)
Step: Click Modify Folder
… Would like container
(id=SubSetAlertOptions)
Step
(id=SelectRecieveAlert): In section Receive Email Alerts, select
Yes.
Step
(id=SelectDayFrequency): In section Day, select the days for which you want to
receive alerts. For example, Monday to Friday.
Step (id=SelectHourFrequency): In section Hour, select the hours for which you want to receive alerts. For example. 9 to 5.
… End container
Step: Click OK
Task3 How to create a news monitoring folder.
…
Steps (id=CreateNewsFolder)
Step: Click Create News Monitoring Folder.
Step: In the Name field, enter a name for the
folder.
Step: Set alert
options which will allow you to receive email notification when new news
documents are added to the folder:
Steps
Container (conref =
SubSetAlertOptions)
Step: Set
Sharing options to allow other users to view your folder's news
articles:
Steps
Container (conref =
SubSetSharingOptions)
Step:
Click OK.
I did not find such a "container" mechanism in the actual DITA architecture. Is it there? If not, is it something we should consider or is it something one should add in its own customized specialization? Is there a no-no or a better solution?
I think it would be very useful for anyone documenting user interfaces. There is so much repetition because there are so many ways of doing one thing from the user perspective. What is really different in creating something and modifying something? Usually, it's only the steps that tell you how to get there.
Also, it is very interesting to document the actual user actions like "share your news folder", "receive alerts", "add search criteria to your news monitoring folder" rather then modify your news folder in which, by the way, you may set sharing options and configure alert notification and add search criteria to find relevant news documents.... It this last case, the instructions on how to get there are all the same. In this case, Click Modify Folder is quite straight forward, but in other cases in could be longer.
France Baril
Documentation
architect/Architecte documentaire
I X I A S O F T
+1 514 279-4942
france.baril@ixiasoft.com
[ www.ixiasoft.com
]