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.
Sunday, January 6, 2008
Demented
I'm a reasonably intelligent person. There are some things I can understand on a conceptual level that I cannot make work on the concrete level, and vise verse. My coordination is great, unless I'm thinking about it. The day I put my lawn mower together was a magnificent day. As far as I was concerned, I'd climbed Mount Olympus and won a wrestling match with Hercules all in one fell swoop. My vocabulary is pretty good, but there are days when polysyllabic explanations leave me muddled and frustrated; being frustrated muddles me even more. Then, when I find out that there is a perfectly good, simple explanation for the concept, I stomp. I get pissed when I'm outsmarted by words. It drives me nuts.
I'm working on two, related, projects right now. In one, I'm learning how to use XSL to play with XML documents. When I see the solutions, I can see, exactly, how it works, but I can't get there on my own. My second project involves DITA (Darwin Information Typing Architecture) and there are three types of conversations about DITA that all revolve around how to do something with the structure of DITA. Some of the conversation is easy, authoring issues - some of the conversations are technical, dealing with XSL or the rendering engines - some are just beyond me and I have no idea what they're talking about. My three buckets. One I can follow, and often get ideas from, one that I can peer vaguely into and get the gist of, one I am left wondering just what the writer is saying and what they're saying it about.
I would sigh, in fact I did, but that is not something that really works in this medium.
If the medium is the message, I'm wondering what I'm missing. The whole idea of simplicity, in this case I'm exchanging my reader-facing simplicity for my creator-facing simplicity. I'm balancing a huge technical weight hoping that I will be delivering, to my reader, a clear, focused result. Something that will make their experience simpler.
I just wish it didn't leave me feeling like I've just jumped off a bridge because someone else told me it would be a good idea.
I'm working on two, related, projects right now. In one, I'm learning how to use XSL to play with XML documents. When I see the solutions, I can see, exactly, how it works, but I can't get there on my own. My second project involves DITA (Darwin Information Typing Architecture) and there are three types of conversations about DITA that all revolve around how to do something with the structure of DITA. Some of the conversation is easy, authoring issues - some of the conversations are technical, dealing with XSL or the rendering engines - some are just beyond me and I have no idea what they're talking about. My three buckets. One I can follow, and often get ideas from, one that I can peer vaguely into and get the gist of, one I am left wondering just what the writer is saying and what they're saying it about.
I would sigh, in fact I did, but that is not something that really works in this medium.
If the medium is the message, I'm wondering what I'm missing. The whole idea of simplicity, in this case I'm exchanging my reader-facing simplicity for my creator-facing simplicity. I'm balancing a huge technical weight hoping that I will be delivering, to my reader, a clear, focused result. Something that will make their experience simpler.
I just wish it didn't leave me feeling like I've just jumped off a bridge because someone else told me it would be a good idea.
Labels: authoring, dita, hapless, XSL
Subscribe to Posts [Atom]
