At IXIASOFT, our CCMS runs on Eclipse, so our user and admin guides are provided as Eclipse documentation (generated using the DITA-OT Eclipse plugin), in addition to HTML and PDF files available on our website. In our latest release, we decided to add context-sensitive help (CSH) to the CCMS so that our users could get help as they were doing their tasks.
Sounds simple, right? Not exactly.
As Dan Elfanbaum mentioned in his article, it’s almost impossible to find information on how to integrate CSH from DITA into Eclipse. Yan Periard, our Chief Artisan, and I sat down to determine how we would approach this and we came up with our own method. (Okay, Yan did most of the technical research and coding, but I encouraged him every step of the way :). I’m sharing our solution here in the hope that it might be useful to others.
Our requirements were simple:
To display CSH, Eclipse expects a context file that looks as follows:
<contexts> <context id="panic_button" title="Panic Button Title"> <description>This is the panic button.</description> <topic href="reference/panic_button.htm" label="Panic Button Reference"/> </context> ... </contexts>
Eclipse requires the following information in the context file:
So our challenge was: How do we go from DITA source code to the context file required by Eclipse? We first thought about creating a specialization that would map exactly to the context file, but we try to stay away from them for usability. We wanted our solution to be as generic as possible.
So we came up with the following approach:
Mapping the information required by Eclipse into a DITA map was fairly straightforward, but we had one complication. Our product can be used with oXygen and XMetaL, and the user guide is XML-editor specific, so it’s packaged in two different Eclipse plugins:
– DITA CMS User Guide for oXygen (com.ixiasoft.eclipse.help.userguide.oxygen)
– DITA CMS User Guide for XMetaL (com.ixiasoft.eclipse.help.userguide.xmetal)
Most customers use one of these XML editors, but some use both. This meant that when clicking F1 on an area of the UI, some customers had to be shown the oXygen version of the documentation, some customers the XMetaL version, and other customers needed both versions. We therefore had to find a way to conditionalize the <topic href> required by Eclipse. After some discussion, we ended up with the following map:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd"> <map id ="lar1410796284657" xml:lang ="en-us"> <title> DITA CMS User Guide Context Map</title > <topicmeta id="help.plugins.root" > <resourceid appname ="com.ixiasoft.eclipse.help.userguide.oxygen" id="Oxygen"/> <resourceid appname ="com.ixiasoft.eclipse.help.userguide.xmetal" id="XMetal"/> </topicmeta > <topicgroup id ="referable_content_view"> <topicmeta> <navtitle> About the Referable-Content view</ navtitle> <shortdesc> The Referable-Content view lets you search for reusable components and insert them into documents.</ shortdesc> </topicmeta> <topicref href ="lar1396892881040.xml"/> <topicref href ="lar1399915347457.xml"/> <topicref href ="lar1399921717895.xml"/> <topicref href ="lar1397657467945.xml" product="XMetal"/> <topicref href ="lar1397657445991.xml" product="Oxygen"/> </topicgroup> </map>
We mapped the information required by Eclipse to DITA elements or attributes as follows:
The map above shows only one topicgroup, for simplicity, but obviously I created one topicgroup for each area of the UI that would benefit from additional information.
For this, we created our own transformation, which basically takes the DITA context map and transforms it into an Eclipse context file (contexts.xml) using an XSLT transformation. We implemented this transformation using the Output Generator, which is the IXIASOFT DITA CMS module that outputs DITA source into the required output type, but you could easily reproduce this as a DITA-OT script. It uses Ant code, as follows:
<target name="dita2eclipsecontexthelpwrapper"> <xslt processor="trax" in="input_map.ditamap" out="contexts.xml" style="ixiasoft_eclipse_csh_transfo.xsl"> <xmlcatalog id="ixia.dita.catalog"/> </xslt> </target>
(For your convenience, you can find the XSLT file here; right-click the link to download the file).
The output contexts.xml looks like this:
<?xml version="1.0" encoding="UTF-8"?> <contexts> <context id="referable_content_view" title="About the Referable-Content view"> <description>The Referable-Content view lets you search for reusable components and insert them into documents.</description> <topic href="PLUGINS_ROOT/com.ixiasoft.eclipse.help.userguide.oxygen/lar1396892881040.html" label="Working with the Referable-Content view"> <enablement> <with variable="platform"> <test property="org.eclipse.core.runtime.isBundleInstalled" args="com.ixiasoft.eclipse.help.userguide.oxygen"/> </with> </enablement> </topic> ..... </context>
Once the contexts.xml file is generated, it’s packaged with the two DITA CMS documentation plugins for XMetaL and for oXygen. And voilà! You have CSH that looks something like this when users press F1:
The help window is opened as an Eclipse view (shown below), so it’s unobtrusive and gets updated as the user moves around the UI.
The OASIS committee has been working hard at preparing the new release of the DITA specification, DITA 1.3, which is currently planned for Q1 of 2015. In addition to bug fixes and miscellaneous quality improvements, DITA 1.3 will introduce some very interesting features, including:
My original plan for today was to cover all the new features, but it made for a very long blog post. So instead I’ll go over each important feature in separate posts over the next few weeks. If you’re impatient and want to know the details of the DITA 1.3 specification right now, see the links at the bottom of this post.
Note: Since DITA 1.3 is not released yet, the specification may change and the information and samples in this post may need to be revised.
Let’s start with context-sensitive help.
The current DITA specification is very limited in terms of support provided for context-sensitive help (CSH). DITA 1.3 plans to address the following two limitations:
When generating CSH from DITA, the
<resourceid> element can be used to specify the callback ID, which is the hook used to link the DITA topic to the appropriate user interface area. For example, we used the
<resourceid> element as follows for the Web Author help:
<prolog> <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/> </prolog>
The problem with DITA 1.2 is that the
<resourceid> metadata is limited in the information it can contain to differentiate between multiple target outputs. For example, consider a topic that is used in three different target outputs: Online help, embedded user assistance, and mobile help. If each target application uses its own callback ID scheme, then multiple different context IDs must be specified for the same topic. Since this information cannot be specified in the DITA 1.2
<resourceid> metadata, the mapping between the DITA source topic and the callback IDs must be maintained outside of the DITA files.
To solve this issue, DITA 1.3 adds three new metadata attributes to
appid: Identifies a referenced topic to an external application
ux-context-string: Specifies a callback context ID for that topic
ux-source-priority: Since the
resourceidmetadata can be set at the map level or the topic level, this attribute specifies how to resolve conflicts between callbacks defined in a map and in a topic; valid values are
topic-takes-priority. So if the
resourceidinformation provided in the topic is different from the
resourceidprovided for that topic in the map, this attribute specifies which
For example, the following code configures callbacks for two target outputs for the create_image topic: One for the Web Author application and one for the Eclipse Client.
<map title=”DITA CMS Help”> <topicref href=”create_image.dita” type=”task”> <topicmeta> <resourceid appname=”cms.webauthor” appid=”create_image” ux-content-string=”com.ixiasoft.webauthor.help.create_image” ux-source-priority=”map-takes-priority”/> <resourceid appname=”cms.eclipseclient” appid=”create_image” ux-content-string=”com.ixiasoft.eclipseclient.help.create_image” ux-source-priority=”map-takes-priority”/> </topicmeta> </topicref> </map>
I’m assuming that the
appid attribute in DITA 1.3 is replacing the
id attribute in DITA 1.2, since I don’t see why we would need both.
To provide the details of the target display, DITA 1.3 also adds a new element,
<ux-window>, and a new attribute for
<ux-window>: This element lets you configure a target display profile and include information such as the size of the window, some of its features, etc. For example, the following
<ux-window>element configures the display for a mobile environment:
<topicmeta> <ux-window id=”task_window” name=”mobile_ios” top=”10″ left=”20″ height=”400″ width=”500″ features=”status=yes,toolbar=no,menubar=no,location=no” relative=”true” full-screen=”no”/> </topicmeta>
ux-windowrefattribute of the
resourceid, as shown below:
<resourceid appname=”cms.webauthor” appid=”cms.webauthor.mobile” ux-content-string=”com.ixiasoft.webauthor.help.create_image″ ux-source-priority=”map-takes-priority” ux-windowref=”mobile_ios”/>
I’m not sure yet about this new improvement. One of the strengths of DITA has always been to separate the source content from how it will look in the output. I see this kind of specification as more appropriate in a transformation scenario. But maybe it’s a requirement for mobile environments, and since I haven’t had to produce mobile help yet, I’m not allowed to complain. :)
In the next post, I’ll cover the new topic type for troubleshooting. Should be interesting!
(This post is part of the Learn DITA on Your Own series.)
A great way to keep abreast of what’s happening in the DITA world is to get connected with the very active and dynamic DITA online community. By following a few blogs, Yahoo/LinkedIn groups, and Twitter accounts you can get the latest news on DITA, read about interesting implementations, and develop your knowledge.
Even if you’re not an active participant in this community, being connected is very useful. I don’t participate much in these groups (I have the luxury of working with DITA experts who can answer any question that I have), but I have learned a lot by reading about other people’s problems, questions, and solutions.
So here are the groups, accounts, and blogs that I follow regularly. Don’t hesitate to let me know if I have missed one that should be on this list.
The best technical reference on DITA is the DITA Users Yahoo Group. It’s the one resource that I follow quasi-religiously. Some of the best DITA experts are there, sharing their knowledge. Some of the questions (and answers!) go way over my head, but I have learned about new concepts and new ways of using DITA thanks to this group. (And I think I’m secretly hoping I’ll learn by osmosis simply by hanging around these experts :).
There are a few DITA groups on LinkedIn, but here are the two that I follow more regularly:
There are also a few regional DITA groups (for example, France, Japan, Alberta, Central Texas), so it might be worthwhile to search for DITA groups in LinkedIn, since there might be one for your area.
I have compiled a list of DITA Twitter accounts that I follow. You can find it here:
You can subscribe to the list or create your own. Again, this is not a complete list, so don’t hesitate to suggest accounts I could add.
There are so many blogs out there on DITA, I couldn’t possibly list them all. Here are my favorite ones:
I hope that you enjoyed this series. Learning DITA has been a great boost in my career, and I wanted to share my enthusiasm with fellow writers interested in learning new technologies.
In a few weeks, I’ll post about how you can create a portfolio of your DITA content. But in the meantime I have to prepare for my presentation at the STC Summit 2014 in Phoenix, Arizona, coming next week. I hope to see you there! :)
In a post that I published last year, I said that I would document how we implemented Ray Gallon’s double-embeddedness theory for a project we were developing. Here I am, a year later, with the details of this implementation. Better late than never, right? :)
Let’s start by summarizing Ray’s theory.
There are two main concepts in this theory:
The solution is what Ray calls “double embeddedness”:
…with progressive disclosure:
In summary, we want user assistance that:
I sat down with the developers at IXIASOFT to discuss how we could implement this theory in our new product, called Web Author. The Web Author is a web editor that allows casual contributors and reviewers to edit and review DITA topics from an Internet browser. Because users would not be familiar with DITA and would not use this tool every day, it was a perfect candidate for the type of user assistance that Ray talked about.
We started by defining three levels of help.
When users hover over an element of the UI, a pop-up is displayed with a short overview of the function. The tooltip provides some conceptual information to put users in context as they are performing the task.
The following diagram shows a sample tooltip. When a user logs in, the Web Author lists the documents that are assigned to the user. The number of documents assigned is displayed in the Number of assignments area. When users hover over this area (the purple square with a number in it), the following tooltip is displayed:
The tooltip contains a More… link so if users need more information about the area, they click the link and level 2 help is displayed.
Level 2 help provides more detailed information about the area as well as links to what you can do in this area (i.e., the actual procedures). For example, if a user clicks More in the Number of assignments tooltip, the following window is displayed:
The level 2 help is not displayed in a pop-up window, it’s embedded in the user interface, in the lower left corner of the main window, as shown above.
Another requirement of Ray’s theory is that help should be unobtrusive and be out of the way if users don’t need it. For this, we added the hide tips/show tips toggle button on top of the help details window (shown above). When users are familiar enough with the user interface and no longer want the help, they can simply disable it by clicking hide tips. Should they need to see the help again later on, they simply click the show tips button.
If a user still needs more information, clicking one of the related links will open the level 3 help.
This is a standard HTML help system available in another tab of the browser. When users click the links in the help details area, they are taken to the corresponding procedure in the online help, shown below:
To implement the user assistance, we decided to use the DITA
<resourceid> element and
To link the DITA topic to the appropriate user interface area, we use the
<resourceid> element in the
<prolog>. For example, to specify the topic that applies to the Number of assignments area, we added the following code to the topic:
<prolog> <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/> </prolog>
appname specifies the product name (in this case, the Web Author) and the
resourceid specifies the resource id of the area as specified in the Java code. This ensures that when a user hovers over an area, the Web Author knows from which topic to pull the documentation.
<resourceid> element for context-sensitive help is a pretty standard approach. What’s different about our implementation is that we decided to use the
outputclass attribute to identify what to display at each level of help.
We defined three values for outputclass:
outputclass="help_tooltip": Defines level 1 help
outputclass="help_context": Defines level 2 help
outputclass="help_related_information": Defines the related links that will open the HTML help
For example, the following code shows the DITA file for the Number of assignments topic:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE concept PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "../../system/dtd/ixia/IxiaDitabase.dtd"> <concept id="per1389986405854" xml:lang="en-us"> <title>Number of assignments area</title> <shortdesc outputclass="help_tooltip"><ph id="number">Displays the number of documents assigned to you in the role selected.</ph> </shortdesc> <prolog> <resourceid appname="cms.webauthor" id="com.ixiasoft.help.assignments.number"/> </prolog> <conbody> <section outputclass="help_context"> <p>When you select a role in the <uicontrol>Roles</uicontrol> drop-down list, all the documents assigned to you and active for that role are displayed in the Assignments pane, and the number of documents is updated in the <uicontrol>Number of assignments</uicontrol> area.</p> <p>To refresh the list and the number of active documents, click the <uicontrol>Refresh</uicontrol> icon in the <wintitle>Number of assignments</wintitle> area.</p> </section> </conbody> <related-links outputclass="help_related_information"> <link href="per1389986405575.xml#per1389986405575" outputclass="help_related_information_link"/> <link href="per1389986404838.xml#per1389986404838" outputclass="help_related_information_link"/> <link href="per1389986405139.xml#per1389986405139" outputclass="help_related_information_link"/> </related-links> </concept>
When a user hovers over the Number of assignments area, the user assistance looks for the element with the
outputclass="help_tooltip". This is usually the
<shortdesc> element. If a user clicks the More… link, the user assistance then looks for the element with the
outputclass="help_context". In the example above, the attribute is set on the
<section> element, so this whole element is included in the help details. The related links specified with the
outputclass="help_related_information" are displayed at the bottom of the help details. If a user clicks one of these links, then the user assistance opens up the complete HTML help.
This is shown in the following diagram (you might want to click the diagram to enlarge it and see the details):
One of the advantages of using the
outputclass is that it’s valid on any DITA element, so it’s very flexible; the user assistance only needs to look for the defined
outputclass, no matter the type of topic. We can use any element in any type of topic to produce the user assistance.
Another advantage of using the
outputclass attribute is that the same source content can be used for the user assistance, the HTML online help, as well as a PDF User Guide that was requested by our customers. But this will be the subject of another post, since this one is getting long enough already.
As you can see from this approach, a lot of magic happens behind the scenes (i.e., in the software) to enable this user assistance. I am lucky enough to work with developers who think that documentation and user assistance are very important, so they decided to treat the user assistance as a feature of the product. They developed a custom XSLT transformation scenario that generates an .hlp file with the user assistance. They also added code to the Web Author that extracts the right level of help according to user actions.
So yes, this method requires custom code from developers, but I think it’s a great example of how DITA can be used to create context-sensitive help.
Again, special thanks to Ray Gallon for his research and very inspiring webinar.
(This post is part of the Learn DITA on Your Own series.)
Learning a new skill takes time and effort. We have the best intentions, but we also live busy lives. How many times have I bought a book with the intention of learning a new subject, read a few chapters, and then put the book aside, never to return to it? It’s not enough to have a goal; you must also put a specific training plan in place to achieve your goal. I’m a runner, and I know that if I want to achieve a new goal, whether it’s running a long cross-country race or establishing a new personal record, I need a plan.
So, how do you develop a plan for learning DITA?
A real project will give you a purpose for completing your training. And since you’ll need content when creating different object types in DITA (such as tables, cross-references, procedures, etc.), without a specific project in mind, you may waste time trying to come up with content.
For example, you could convert one of your existing user manuals to DITA. You could also take content that is freely available on the web, under a Creative Commons license (which means that you are free to copy and redistribute the material in any medium or format, as long as you don’t use it for commercial purposes), and create a DITA version of it. To find such documentation, search for the following string in Google: “documentation is licensed under a Creative Commons Attribution”.
Another advantage of using a real project is that you can then include it in your portfolio to show potential employers (more on this in an upcoming post).
A great training book will explain the DITA concepts and provide exercises so that you can apply your knowledge. There are many books available, but here are my recommendations:
This book is a great introduction to DITA. It also includes 24 lessons that cover most DITA concepts, from creating a topic to creating a Ditaval file for processing. Throughout the book, you create a small user guide for a fictitious phone system. I recommend the electronic version (available from ComTech here), so that you can copy and paste code samples if you don’t want to type them out. (I can’t say that I particularly like the interface of the electronic version, but being able to copy and paste code makes is worth the not-so-friendly interface).
This is the perfect book for writers who aren’t too technical; the concepts are explained simply and clearly and the book is very easy to follow. The main problem with this book is that most examples are not provided in DITA code; instead, elements are displayed visually. This is great if you’re using a visual DITA editor; otherwise, it’s not that useful. Also, this book was released before DITA 1.2 was out, so it’s missing important 1.2 features such as keyrefs and conrefs. But it’s a great introduction to DITA.
This book is organized in two parts: The first one introduces the main DITA concepts and provides great tutorials that take you through the steps of creating DITA content and generating it using oXygen and the DITA Open Toolkit. The second part goes over each concept into more details. You can download the code samples used in the document so that you don’t have to type them. Two small warnings about this book: It uses the oXygen DITA editor in the examples, so while you can still create and run your content using Notepad++ and calling the DITA OT directly from the command-line, you’ll need to do a bit of work on your end to perform the procedures. Also, while this is probably my favorite DITA book, I read it once I already knew about DITA, so I’m not sure it’s the best introduction to DITA for writers. Kimber is a DITA guru and a very technical guy, so this book may be more difficult for the less technically inclined.
Learning a new skill takes time. If I want to reach a race goal, I need to run at least three to four times a week. With work, family, and side projects, I’m very busy, so if I don’t plan ahead the times when I’ll go running, I don’t make it.
In the same way, you need to plan ahead your DITA training time. For example, you could plan to work on your DITA training every Tuesday evening, two evenings a week, or every second Saturday. The important thing is to select a time that is reasonable and doable for you, according to your schedule. Otherwise you may get discouraged and abandon your plan.
It’s not enough to simply plan when you’ll work on DITA; you also need to know what you will be learning! I recommend organizing your training around the book that you’ve selected and creating a spreadsheet that lists the DITA concepts covered in the book.
As an example, you can download here an Excel Spreadsheet that contains sample training plans for two of the books listed above, Introduction to DITA and <dita> for Practitioners. You can then use it to track your progress and see how well you’re doing.
While Notepad++ will work just fine to learn DITA, it will not check your DITA structure and does not provide a visual interface. I have been using oXygen for the past three years and I love it. You can get the latest version for $349. It’s not cheap, but it’s not overly expensive, and you will be able to add oXygen to your list of skills. There are other XML editors available; the best up-to-date list of XML editors that provide DITA support is available through the DITA Writer, in his article List of DITA Optimized Editors. You can also request a one-month free trial license for most of these vendors.
Note that this is completely optional. You can very well use Notepad++ and run the DITA Open Toolkit from the command-line…you know it works, because you’ve done the World’s Smallest DITA Project using these tools! The good news with Notepad++, though, is that you’ll be quite the expert in DITA authoring once you’re done with your training! If you plan to use Notepad++, the Introduction to DITA, Second Edition is probably your best choice in terms of book.
With a plan, a book, and the tools, you have all that you need to learn DITA on your own…now get to work! :)
In the next post, I’ll cover essential DITA blogs, user groups, and Twitter accounts that you should follow to get connected with the DITA community.
I’ve developed a lot of content in my life as a tech writer, but content strategy is a field that still puzzles me. What does it mean exactly? Why is it so important? And what on earth are transclusions, wireframes, and folksonomy? I finally found the book that answered all my questions: The Language of Content Strategy.
Published by XML Press, The Language of Content Strategy is a very unique book. Edited by Scott Abel (best known at the Content Wrangler) and Rahel Anne Bailie, it provides short texts written by 52 experts in the field of content strategy. Each text describes a term used in content strategy, and the terms are grouped into five categories: core concepts, core deliverables, technical concepts, extended deliverables, and global content.
I was afraid that reading a “dictionary” of content strategy terms might be tedious, but I very much enjoyed The Language of Content Strategy. The language is crisp and dynamic, the descriptions read very well, and enough information is provided to clearly explain each term without drowning the reader with too many details. I often found myself underlining sections of the book and taking notes in the margins for topics I wanted to explore, and I know that I’ll go back to this book for reference.
Each text also includes a short bio of the contributor, which allowed me to come up with a list of other books I want to read, as well as blogs and Twitter accounts I want to follow. Clearly, the editors gave much thought to the content and organisation of this book. They know content!
If you want to find out more about content strategy, I highly recommend The Language of Content Strategy. It will be available on Amazon later this week.