"Conref, conkeyref, conrefpush" - reuse strategies in DITA when migrating legacy content
•Download as PPTX, PDF•
2 likes•1,337 views
This is the presentation I gave during the Soap! 2015 conference in Krakow.
Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Similar to "Conref, conkeyref, conrefpush" - reuse strategies in DITA when migrating legacy content
Similar to "Conref, conkeyref, conrefpush" - reuse strategies in DITA when migrating legacy content (20)
Recently uploaded
Recently uploaded (20)
"Conref, conkeyref, conrefpush" - reuse strategies in DITA when migrating legacy content
- 1. @conref @conkeyref @conrefpush REUSE STRATEGIES IN DITA WHEN MIGRATING LEGACY CONTENT 1 2015 Conference
- 2. © Adam Sanyo, 2015 2015 Conference Agenda Why companies decide to adopt DITA? Planning the migration of legacy content How to reuse content in DITA Examples 2
- 3. © Adam Sanyo, 2015 2015 Conference My background Five years of experience in technical writing. Worked on two different migration projects. Degree in English and Linguistics. Currently working for ARM as an information developer on a contract basis. “Love at first sight” when encountering DITA in 2010. 3
- 4. © Adam Sanyo, 2015 2015 Conference Why companies decide to adopt DITA? Because they want to do any of the following: Reuse content across products. Reduce costs (for example, translation or authoring cost). Share workload between individual writers (increase productivity). 4
- 5. © Adam Sanyo, 2015 2015 Conference DITA adoption scenarios The company wants to manage a large document set from a component content management system (CCMS) and wants to get rid of authoring silos. Different authoring teams create similar content and some of that content could be reused. The company wants to translate its document set effectively and wants to reuse translations over time. 5
- 6. © Adam Sanyo, 2015 2015 Conference Strategy for legacy content migration Note: I will not cover budget considerations (as I have never done that part), but I will cover the technical side. Select part of your content as a test and see how you can reuse and restructure it (run a prototype project). Have at least some rough reuse processes and guidelines. Write a good conversion script (that transforms legacy content to XML). Visualize your end product (the outcome of the project or a deliverable). 6
- 7. © Adam Sanyo, 2015 2015 Conference Authoring decisions Let us assume that you are using the standard DITA framework (task- concept reference topics) and maybe one or two extra topic types on top of that. Identify your topic types and chunk the content accordingly. Start with task topics as those are the easiest ones to identify but the most difficult ones to convert (because of DITA-constraints in task topics). Select your reuse strategy after you analyzed your content. Decide the level of deviation from the original content (is your project a simple conversion of your content or do you want to rework some parts of the text?). 7
- 8. © Adam Sanyo, 2015 2015 Conference Some general reuse rules Gain flexibility by using keys (because they create a dependency only on the map level). Reuse block elements (paragraphs or elements with similar size), but you can reuse smaller elements if they do not require translation (for example, product names or version numbers). Rewrite two or more similar topics if they become reusable after that. 8
- 9. © Adam Sanyo, 2015 2015 Conference Using @conref Definition “Content reference”, that is, referencing one piece of content from one topic to another. Reuse strategy You want to reuse universal content found in many or all publications. Example Copyright information Limitation Make sure that the referenced content is correct in all publications where it is used, or you must maintain different versions of the text. 1. Content is created in a reusable topic (“reusable_topic.dita”). 2. The topic id and the element id is used in the reference (topic id: “reuse”, element id: “copyright”). <p conref="reusable_topic.dita#reuse/copyright"/> Output: © All rights reserved, 2015. 9
- 10. © Adam Sanyo, 2015 2015 Conference Using @conkeyrefs Definition “Content key reference”, which is an indirect content reference governed by defined keys on the map level. Reuse strategy You have few differences between topics in your product. Example Changing elements between similar products using keys (e.g. version numbers of products). Limitation Managing the content on the map level using a reference topic can become difficult and results in too much overhead over time. 1. The key is defined on the map level with reference to a topic that contains the content. <keydef href= "reference.dita" keys="variables"/> 2. The key that is assigned to the topic and the id of the referenced content is used for referencing content. Reference to the topic: “variables” Reference to the element id in the topic: “version” <keyword conkeyref="variables/version"/> Output: Version 15 10
- 11. © Adam Sanyo, 2015 2015 Conference Using conditional processing/profiling (DITAVAL) Definition As the name suggests, conditional values are defined to select given parts of the full content. It is also called content profiling. When to use Useful for authors when they create content for multiple audiences It is easier to manage attributes than keys (up to a certain point). Example The same topic is sent to different clients, and some parts of the text are client-specific. Limitation It is better to store the content pieces in separate topics rather than having a big master topic with all the content. 1. Define the DITAVAL attributes, for example, to exclude a given version number. <prop action="exclude" att="audience" val="version15"/> 2. When generating your output, add this DITAVAL file to your scenario and the output will not contain what you excluded. Note: As long as something is not excluded, it will be included. 11
- 12. © Adam Sanyo, 2015 2015 Conference Using @conrefpush Definition Push some content before, in place of, or after a marked section. When to use It is recommended as a temporary solution only. Limitation Compared to keys, it can be hard to manage many conrefpush scenarios, and it is also harder to set up conferpush scenarions for a novice DITA user. 1. Give an id to the element where your new content would be in your content topic and use a conref to add this selected element into your reference topic (the topic that contains the new content you want to add). 2. Add the “mark” conaction attribute to the referenced content. 3. Create the new content in the reference topic. 4. Add the reference topic with resource-only outputclass attribute to your main content map. More info: http://dita.xml.org/resource/dita-12-feature- article-conref-push 12
- 13. © Adam Sanyo, 2015 2015 Conference Examples (in oXygen XML Author) Using conditional processing (in a master topic) Using @conkeyrefs (on two maps) Using @conrefpush 13
- 14. © Adam Sanyo, 2015 2015 Conference Contact information 14 Adam Sanyo info@sanyowritingsolutions.co.uk
- 15. © Adam Sanyo, 2015 2015 Conference If I timed myself right, we have 10 minutes for questions Questions? 15
Editor's Notes
- Icebreaker, thank the organizers for organizing the event, tell the story about the visit to Krakow
- POLL: who is from a technical writer background, who is not, who is familiar with DITA? Focus on two things: 1. legacy migration AND 2. general DITA reuse
- Introduction, humanities background, currently contracted by ARM, 2nd migration project „We have all probably seen this picture when we’ve done a search on DITA... Von Tesse”
- DITA is an industry standard that promotes reuse. Sharing workload – you need at least 3-4 writers to see the benefits of DITA. Also, it is not the size of your team but the content you create will define the reuse potential you have.
- Getting rid of silos is the top priority because you both increase productivity and reduce waste (i.e. two people working on the same content). The saving on translations can be massive if you need to translate all your content
- Prototype – for example, a new release will come out shortly and you want to build that on existing content Conversion script – conversion tables from Framemaker to DITA + XSLT End product – what will you do with your migrated content? Is it going to be used for as reference content or is it going to be a full manual?
- Chunk topics – task topics should be in the focus especially in software documentation Reuse strategy is formed while analyzing content, it is not a „set in stone” strategy Level of deviation – important because it decides the potential for future reuse
- Keys – indirect references to topics (usually reference topics), they are defined on the DITAMAP level. Each DITAMAP can use different sets of keys from a reference topic. So the content is in the reference topic, but the way that reference topic is defined is different (the key makes it an indirect reference, therefore, it is more flexible than other references). Rewrite topics – try to be generic rather than specific when writing a topic (turn on printer vs. Turn on monitor, almost the same turn on device)
- Conref – pulling content from one place to another. The content is stored in a reference topic, it is good to have a reference topic that collects these content pieces (unless the content pieces could form a full topic)
- Indirect reference – the small differences between two products are best managed by content key references. You can treat these differences as variables, just like you treat the keys as variables In the example: The keydef can point to one reference topic in one map, and another one in another map. The „keys” value remains the same, but it will point to two different source files.
- Madcap Flare users – it is almost the same as the profiling feature of Flare. You can manage different profiling attributes just as you manage keys for your content. It is useful to create master topics where you create content for multiple audiences and then just pick and mix the bits you need. As long as something is not excluded, it will be included! (important)
- Conrefpush is a relatively complex – at least for me – concept in DITA. You create some content that you want to push before or after your existing content. It is basically a content reference with a marked location to which you add this content. It is recommended as a temporary solution only. More info, see the feature’s description (and my example shortly).
- One topic shows the use of all these features in oXygen XML Author