Tasks in Manuals

[BuckH]

I am evaluating oXygen and DITA to determine if they will work in my situation and I have a question that I cannot find an answer for.

A lot of my manuals contain very similar procedures but have minor variations between them. For example, let’s say I have a manual for carrots and a manual for potatoes. The instructions for washing and peeling them are the same. But during the peeling part, I need to add a step in the potato manual to remove the eyes and black blemishes. And the chopping instructions are different between carrots and potatoes. Instead of combining the two manuals, I need two separate manuals because potato people don’t want to read about carrots and vice versa.

Is there a way to deal with this in oXygen or DITA? Would I need to save each step as a separate task file? I don’t want to repeat anything if I don’t have to. That’s what I’m trying to get away from.

Any help or insight is appreciated. Thanks!

[Radu]

Hi,

I would try to do this using a DITA 1.2 feature called content reference push (but also use keyrefs for the product name):

http://www.oxygenxml.com/dita/styleguid ... _Push.html

How this would work:

You have a DITA task task.dita like:

Code: Select all

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="taskID">

    <title>Peeling <ph keyref="productName"/></title>

    <taskbody>

        <context>

            <p>Steps:</p>

        </context>

        <steps>

            <step id="wash">

                <cmd>Wash the <ph keyref="productName"/>.</cmd>

            </step>

            <step>

                <cmd>Peel the <ph keyref="productName"/>.</cmd>

            </step>

        </steps>

    </taskbody>

</task>

The task only contains the common steps and uses <ph keyref="productName"/> for the product name (in Oxygen on the DITA toolbar there is a drop-down link button which allows you to insert key references).
Also the first step has an ID defined on it. This is important because we will use that ID as an anchor to push an extra step after it.

The DITA Map for potatoes is called potatoes.ditamap and would look like:

Code: Select all

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">

<map>

 <title>Potatoes</title>

 <keydef keys="productName">

  <topicmeta>

   <keywords>

    <keyword>potatoes</keyword>

   </keywords>

  </topicmeta>

 </keydef>

 <topicref href="task.dita"/>

 <topicref href="pushExtraTaskSteps.dita" processing-role="resource-only" toc="no"></topicref>

</map>

As you see, the DITA Map defines the "productName" key which is used in the task.
It also refers to a second task called "pushExtraTaskSteps.dita" which will not appear in the output and it's main role is to push content to the common task.
It's content is:

Code: Select all

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="task_h1x_jkc_4s">

    <title>Push extra steps task</title>

    <taskbody>

        <context/>

        <steps>

            <step conaction="mark" conref="task.dita#taskID/wash">

                <cmd/>

            </step>

            <step conaction="pushafter">

                <cmd>Remove the eyes and black blemishes</cmd>

            </step>

        </steps>

    </taskbody>

</task>

So this task which does not appear in the output first targets the first step in the common task and then injects another step after it.

You could try to create these samples on your side and play with them.

For the "carrots" user's manual the "carrots.ditamap" would have about the equivalent content of the "potatoes.ditamap" but it would define another product name and it would have a push task which would push other steps in the common task.

As a recommendation you should also consider registering on the DITA Users List:

https://groups.yahoo.com/neo/groups/dita-users/info

It is a very good place where to ask either general questions about how your project should be structured or publishing questions.

Regards,
Radu

[Radu]

I forgot something,

As an alternative to my rant above you can use profiling attributes.
The original task would contain besides the common steps also the steps specific to carrot and potatos, but each step would have an explicit profiling attribute set on it like: "audience='potato'".
Then when you would publish for "potato" you would use a DITAVAL filter file to remove all other audience values.

Regards,
Radu

[BuckH]

Radu,

Thank you very much for your thorough explanation. That is good news that DITA can handle this. I appreciate you providing two solutions. The second one may suit my needs better. If I write another manual in the future for another vegetable, I could add specific steps that could be filtered. I know the following is not correct syntax, but these are my plans based on my understanding:

Code: Select all

<DITA header stuff>

<task peeling>

Peeling steps:

<steps>

<filter=peeled>Lightly scrape the peeler against the <ref=veg> until the skin is removed.

<filter=onion>Remove the crunchy outer skin of the <ref=veg>.

<filter=potato>Remove eyes and blemishes.

Wash under cool water.

</steps>

</task>

It sounds like I will need an overwhelming amount of planning to convert to DITA.

Thanks for the link to the user group. I was unsure of the best place to ask questions.

Thanks again!
Buck

[Radu]

Hi Buck,

Thanks for the link to the user group. I was unsure of the best place to ask questions.

The Oxygen forum is a more static place (registered users only receive updates for their own posts).
So in cases in which you want to see more possible approaches from various DITA implementers you can write on the DITA Users List or at least on the Oxygen Users mailing List.

Regards,
Radu