Thursday, January 24, 2008
Copy-to Attributes
We have a number of products (ultrasound systems) that share a basic document structure and include super- and sub-sets of a range of features. It made sense to us that we would have maps that contain the standard document sections and each map topicref element is tagged to indicate the products that support the feature discussed (or in the case of tasks, the specific set of steps in the procedure). If our product was a car it would be akin to having standard topics that describe what the various parts of the car are and more variance in the topics that describe where to find the parts and how to use the car.
In some cases, different sections of the manual include the same topic. If, for example, the car manual had a discussion about tires and the author responsible for the section that covers changing the tires wrote it, but the author responsible for the section that covers handling the car in various weather conditions wanted to use it, the resulting book would display the topic in the two locations but references to the topic would always go to the first pointer. So, a topic in the weather conditions section that included a link to the tire discussion would drop the user into the middle of the section that covers changing the tires. Contextually incorrect even thought the content of the topic is correct.
Any related topic links in the topic would appear to point to changing the tires, not handling the car in snow (or other extreme weather).
To get the output to point to the correct iteration of the topic, the contextually correct iteration, you can use the copy-to attribute of the topicref element.
When creating your map, you can set the attributes (and depending on the tool you're using, you may have to switch over to plain text editing to do this) for the product and the copy-to. The copy-to attributes, as I understand it, creates a virtual copy of the topic with a unique name. Using the car example above, that would look like this:
<topicref href="About_Tires.xml" copy-to="About_Tires_Service.xml"/>
<topicref href="About_Tires.xml" copy-to="About_Tires_Handling.xml"/>
To create a link to the version used in the car maintenance section, you use About_Tires_Service.xml in your reference. That brings your reader the contextually correct occurrence of the topic. To create a link to the version of the tire discussion used in the section on driving, you use the About_Tires_Handling.xml.
In some cases, different sections of the manual include the same topic. If, for example, the car manual had a discussion about tires and the author responsible for the section that covers changing the tires wrote it, but the author responsible for the section that covers handling the car in various weather conditions wanted to use it, the resulting book would display the topic in the two locations but references to the topic would always go to the first pointer. So, a topic in the weather conditions section that included a link to the tire discussion would drop the user into the middle of the section that covers changing the tires. Contextually incorrect even thought the content of the topic is correct.
Any related topic links in the topic would appear to point to changing the tires, not handling the car in snow (or other extreme weather).
To get the output to point to the correct iteration of the topic, the contextually correct iteration, you can use the copy-to attribute of the topicref element.
When creating your map, you can set the attributes (and depending on the tool you're using, you may have to switch over to plain text editing to do this) for the product and the copy-to. The copy-to attributes, as I understand it, creates a virtual copy of the topic with a unique name. Using the car example above, that would look like this:
<topicref href="About_Tires.xml" copy-to="About_Tires_Service.xml"/>
<topicref href="About_Tires.xml" copy-to="About_Tires_Handling.xml"/>
To create a link to the version used in the car maintenance section, you use About_Tires_Service.xml in your reference. That brings your reader the contextually correct occurrence of the topic. To create a link to the version of the tire discussion used in the section on driving, you use the About_Tires_Handling.xml.
Subscribe to Posts [Atom]
