Can you confirm my reuse strategy?

[ann.jensen]

Hi,
As our DITA content for our System Documentation grows and as we try to reuse it for many different audiences I would like to get some confirmation of the approach that we are taking in relation to our reuse strategy and implementation.
We have content that is published out to WebHelp for 3 different audiences. Content common for all audiences has no audience profiling while other content relevant to only some audiences has audience profiling.
I handle this with a root ditaval that excludes content for all audiences and then includes content that is tagged only for the relevant audience.

The ditaval for publishing content for audience1

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<val>

    <prop action="exclude" att="audience"/>

    <prop action="include" att="audience" val="audience1"/>

</val>

The root map

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

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

<map>

 <title>Products</title>

 <topicref href="c_products_docs.dita" collection-type="sequence">

    <topicref href="product1/product1.ditamap" format="ditamap" product="product1"

   audience="audience1"/>

    <topicref href="product2/product2.ditamap" format="ditamap"

   product="product2" audience="audience2"/>

 </topicref>

</map>

Some child maps are reused for different products and so we use keyscopes, keyrefs and branch filtering to manage this.

product1.ditamap

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

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

<map keyscope="product1_scope">

 <title>Product1</title> 

  <!-- Keys -->

 <keydef keys="system_name">

  <topicmeta>

   <keywords>

    <keyword>Product1</keyword>

   </keywords>

  </topicmeta>

 </keydef>

 <keydef keys="system_name_internal">

  <topicmeta>

   <keywords>

    <keyword>Product2</keyword>

   </keywords>

  </topicmeta>

 </keydef>

 <keydef keys="system_tabs_img" href="tabs/images/i_system_tabs.png" format="png"/>

 <topicref href="c_product_concept.dita" collection-type="sequence">

  <topicref href="../c_tab_menu_display.dita" collection-type="sequence">

   <topicref href="../tabs/r_tabs_tech.dita" audience="audience1"/>

  </topicref>

  </topicref>

 <ditavalref href="../../../../ditavals/product1.ditaval"/>

</map>

product1.ditaval

Code: Select all

<val>   

    <prop att="product" action="exclude"/>

    <prop att="product" val="product1" action="include"/>

</val>

In product2.ditamap

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

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

<map keyscope="product2_scope">

 <title>Product2</title> 

  <!-- Keys -->

 <keydef keys="system_name">

  <topicmeta>

   <keywords>

    <keyword>Product1</keyword>

   </keywords>

  </topicmeta>

 </keydef>

 <keydef keys="system_name_internal">

  <topicmeta>

   <keywords>

    <keyword>Product2</keyword>

   </keywords>

  </topicmeta>

 </keydef>

 <keydef keys="system_tabs_img" href="tabs/images/i_system_tabs_menu.png" format="png"/>

 <topicref href="c_product_concept.dita" collection-type="sequence">

  <topicref href="../c_tab_menu_display.dita" collection-type="sequence">

   <topicref href="../tabs/r_tabs_tech.dita" audience="audience1"/>

  </topicref>

  </topicref>

 <ditavalref href="../../../../ditavals/product2.ditaval"/>

</map>

product2.ditaval

Code: Select all

<val>   

    <prop att="product" action="exclude"/>

    <prop att="product" val="product2" action="include"/>

</val>

The code for c_tab_menu_display.dita

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="c_tab_menu_display">

 <title>Features and Functionality available in 

  <ph keyref="system_name" audience="audience2 audience3"/>

  <ph keyref="system_name_internal" audience="audience1"/></title>

 <shortdesc>

 <ph keyref="system_name" audience="audience2 audience3"/>

 <ph keyref="system_name_internal"  audience="audience1"/> functionality is provided via a system menu as well as a series

  of tabs. The system menu options and selection of tabs displayed varies depending on the type of

  user logged in to the system. </shortdesc>

 <conbody>

  <section>

   <title>Tabs</title>

    <p><image keyref="system_tabs_img" scalefit="yes"/></p>

  <p>The full list of tabs available are:<ul>

    <li></li>

   </ul></p>

   <p product="product1">This content is relevant only for product1:<ul>

    <li></li>

   </ul></p>

   <p product="product2">This content is relevant only for product2:<ul>

    <li></li>

   </ul></p>

  </section>

 </conbody>

</concept>

All seems to be publishing as we want but I wanted to see if anyone has positive/negative feedback this reuse approach?
Any feedback appreciated,
Regards,
Ann

[Radu]

Hi Ann,

You have quite a complex setup but that's what seems to be needed for your project. The Oxygen forum is a more static place, usually most Oxygen users register to receive notifications only on their started forum threads.
If you want to ask feedback from the DITA community you can register and ask around on the DITA Users List (Yahoo Groups).

Regards,
Radu

[xephon]

Hi,

your strategy looks good so far. You might get problems when reusing maps and go up and down the file hierarchy too often. You will probably break the Toolkit at some point. You should always keep an eye on the log, whether there are any warnings. We now keep all publication maps and container maps in the root directory. This is messy but less error prone. As a thumb role: An href should never ever contain ../ This could be detected by Schematron. Maybe this will work for you and you'll never get problems, but if so, the map structure may be hard to refactor. Also you might need more specific file prefixes at some point for maps and topics and more map and topic types to organize and typify things. We use three letters, like CON (Concept), TSK, (Task) or DTA (Database for conkeyrefed elements). Good luck on your journey. Please share your patterns and concepts on doctales.atlassian.net/wiki.

[ann.jensen]

Thanks for your feedback xephon.
Can you clarify that you keep all maps and topics in the root of your project so that you have no hierarchy when referencing between them?
Regards,
Ann

[xephon]

Hi Ann,

it's our solution to work around DITA-OT issues. For example, if you mix your reuse mechanisms with keyrefs and conkeyrefs, the DITA-OT might break at some point. As I said, this procedure clutters the root directories of our projects, but it simplifies the processing.

Code: Select all

/

├── ProductA

│     ├── ComponentX

│     └── ComponentY

│             ├── Concepts

│             │       ├── CON_ProductA_ComponentY_Foo.dita

│             │       └── CON_ProductA_ComponentY_Bar.dita

│             ├── Data

│             └── Tasks

├── ProductB

├── CTR_ProductA_ComponentX.ditamap (Container Map containing everything for component X of product A)

├── CTR_ProductA_ComponentY.ditamap (Container Map containing everything for component Y of product A)

├── CTR_ProductA.ditamap (Container Map containing all container maps for product A)

├── CTR_ProductB.ditamap (Container Map containing all container maps for product B)

├── MAN_ProductA.ditamap (Bookmap containing CTR_ProductA for manuals)

└── WEB_ProductA.ditamap (Bookmap containing CTR_ProductA for webhelps)

I must say, that we have thousands of conkeyrefs that also contain conkeyrefs.

Greetings,
Stefan

[ann.jensen]

Thanks for that Stefan,
I wonder in my case does it makes sense to place all dita and ditamap files in the root folder directory of our file manager (Windows Explorer).
We do reuse dita files across product ditamaps and so currently the DITA code has a lot of ../ and ../../ and ../../../ etc. in hrefs.
This would yield a very flat file structure with very little organization but would ensure very simple paths within DITA code.
Regards,
Ann