DITA linking best practice at IEn2015

Infomedian of the YearThe three days at Information Energy 2015 in Utrecht have passed too quickly. Everyone seemed to feel at home, the sessions were interactive and fun, speakers and attendants eager to share information and show how they create and publish content in most diverse forms and channels… that’s what makes an infomedian. To round up the experience, apart from teaching a master class and giving a presentation, I had the honor of giving a short interview and being part of the jury in one of the workshops.

The venue also gave it special “energy” – first, Master Classes and presentations at Uni Utrecht, a historical site with classical and retro chambers where the eyes of scientists, professors and artists watched us from old paintings or billboards, followed by workshops at Seats2Meet, a very interesting concept with themed lounges in vintage look.

After the full-day Master Class on the pre-conference day, I also gave a short presentation the next day about DITA Linking Best Practice. We have seen examples and done exercises in the workshop. We have also talked about structured, topic-oriented writing and about DITA architecture: map structure, reuse strategy, authoring environment and publishing pipelines. The presentation afterwards was just the shorthand version of the workshop, but it served to start further discussions. Thank you all for attending! It was great meeting everyone in Utrecht.

Enjoy the prezi and let me know your thoughts:

DITA Linking - prezi

Click the image to open the Prezi slideshow

For the advanced use of keys on topic references, don’t miss the contributions of Gnostyx and Eliot Kimber to the dita-community repository: dita-demo-content-collection

So how are you managing your content linking?

Related posts 😉

DITA Linking Best Practice

Join us (Jang & Magda) for a day’s Master Class on DITA Linking Best Practice at Information Energy 2015

As users of technical information (in a manual, in embedded help or on the web), we use links all the time. Sometimes they lead to the exact topic we need and sometimes we end up running around in a wild goose chase.

So how do you make sure that your users find their information quickly and easily? By setting up the right linking strategy for your product and your business domain. This sounds easier than it might be, as there are various linking strategies and not one of them is the best in all possible situations.

This master class teaches you about the available link management strategies in DITA and gives you a sound basis to decide which strategy works best for your information products.

We’ll explore the various types of linking with hands-on exercises:

  • Element-level linking: linking to graphics, tables, steps, files.
  • Hierarchy linking: links generated by nesting, family collections, sequences.
  • Relationship tables: bidirectional links, uni-directional links, collections.
  • Subject-scheme maps: taxonomy and topic assignment.

Each section starts with a conceptual overview and a set of practical tips and tricks, followed by hands-on work using your own set of DITA topics and maps on your own computer. Each practical session ends with a group session in which you exchange experiences and learn from each other.

After attending this workshop, you will be able to choose a linking strategy that fits your information products like a glove.

Date: June 2, 2015
Time: 10:00 – 16:00
Location: Academiegebouw, Utrecht
Language: English
Costs: €395, including lunch and drinks (Early Bird: €295)

Register for the Master Class “DITA Linking Best Practice

Related links:
Information Energy 2015
JANG Communication

IA and TechComm at EUROIA14

Continuing my flashback notes, after Brighton and Bucharest, let me take you to the third B-named city I had visited within a month: Brussels. I finally managed to attend EUROIA, the Information Architecture conference in Europe last September. They closed the 10-year loop back in Brussels and I joined just in time to celebrate and received a cool anniversary T-shirt.

This was quite a change from the usual techcomm conferences. In my “scrapcloud” attempt I mentioned only a few of the terms that stuck with me from EUROIA14, but it was so much more. It took me to the… “liminal”-zone 🙂

EUROIA14 scrapcloud

We were shown the artistic side of information architecture through presentations about design, architecture, innovation, anthropology and psychology. But in the same time, workshops and presentations confirmed that info architects and user experience designers are facing similar challenges technical communicators do. Lots of familiar images: spreadsheets for content auditing, models to sort, chunk and reuse information. One page per thing was an often mentioned rule, as well as MRUs (minimum reusable units). Ontologies and linking are of course vital, since they are the very mechanism that keeps the web running. Does CORE model sound familiar to tech writers yet? It should: Create Once, Reuse Everywhere. And the statement that probably got just as much ovation and Twitter coverage as the marriage proposal in the end, was the reminder that Content is f*** King!

What also seemed a déjà vu, was the effort of info architects to establish their role and responsibilities within companies and workflows. we are all in the center

After seeing in various projects and books those diagrams with all team members or skills in their little circles, all pointing to the project manager (call it scrum master if you will) in the center, then seeing the same in slides trying to define the technical writers’ job and how they should position themselves and communicate with all other roles in their projects… it was the IA and UX designers’ turn to flip the charts.

Good to know we’re not alone and interesting to see we are trying to connect with the same roles in our projects: managers, developers, engineers, testers, etc.

Can hardly wait for the next EUROIA and I hope to see some more conferences adopting their agenda model:  workshops every morning, presentations and lightning talks in the afternoon, dozens of books to give away each evening.

Link management in DITA

One of the power features of the DITA environment is the linking mechanism. Combined with keys and conditioning, it gives single-source projects unexpected dimensions.

You can steer your linking strategy from the main ditamap of the deliverable in a clean, non-intrusive manner. The topics remain “neutral”, reusable in any number of projects. The content can be reassembled to fit different use cases, audiences, media, just by manipulating the topics hierarchy and the relationship table in the ditamap, without actually touching the topics. And another piece of good news: no more manually maintaining those miniTOCs…

The following examples are created in oXygen Editor v16, and generated using the PDF and the WebHelp scenarios. By integrating your customized plugins for the DITA Open Toolkit, you can further adjust the look and feel of the publications.

Based on the topics nesting in the ditamap, and eventually the collection-type attribute, your publishing scenario can generate links between parent and children topics, links between sibling topics, and links to next, previous and prerequisite topics in a sequence.

The result also depends on how you set the parameter for related links in the publishing scenario or build script. To display the collection links, set the args.rellinks parameter to "all". If set to "nofamily", only the link to the parent topic is displayed, apart from the links generated from the relationship table.

You should also consider, whether you want your plugin to show or hide the short descriptions, and to group the links under a generic Related links label (makes sense to me), or to display the links by topic type: Related concepts, Related tasks, Related information, etc.

Let’s see a few examples of publishing from a ditamap with topics A, B, C, nested under an overview topic. Remember: You add all these links without modifying the topics source!

Example 1: Simple nesting

Map sample with simple nesting

Output: In the PDF, the overview topic (parent) has links to the nested topics (children), and the children link to the parent.

PDF from simple nesting

Example 2: A family collection

Replace line 5 in the map with:
<topicref href="source/ov_topic.xml" format="dita" type="topic" scope="local" collection-type="family">

Output: The parent has links to the children; the children link to the parent and to each other.

PDF with family collection

Example 3: A sequence collection

Replace line 5 in the map with:
<topicref href="source/ov_topic.xml" format="dita" type="topic" scope="local" collection-type="sequence">

Output: Let’s look at the WebHelp output, this time. The parent has links to the children in an ordered list; the children have links to the parent, to the previous and to the next sibling.

WebHelp output of sequence parent
WebHelp sequence child

Example 4: A required task in the sequence collection

Add the importance attribute to a required task in a sequence (line 6).
Sample with required task in sequence

Output: The second and third topics contain a link to the first task, as prerequisite.

WebHelp sequence with prerequisite

To manage the linking between topics that are not hierarchically linked, create a relationship table at the end of the main ditamap of your deliverable. Remember, the map hierarchy also creates certain links, so you should avoid duplicates.

There are more types of relationship tables (reltable), but I prefer staying with the two-column reltable, which allows me to think of links as unidirectional or bidirectional arrows between the two cells of each row.

Apart from linking to DITA topics (concept, task, reference, etc.), you can use the reltable to add links from a topic to external sources, such as web pages or other PDFs.

Example 5: Relationship table

A ditamap with topics A, B, C, D, nested under an overview topic, followed by topics X, Y, Z, and a relationship table.

ditamap with reltable

The example reltable contains three rows:

  • The first row relates topic A to topics X and Y.
  • The second row relates topics C and D with topics X and Z, while X and Z are also grouped in a family (line 30), so they would also link to each other.
  • The last row defines a sourceonly relation (line 36) from topic B to topics A and Z, which means A and Z will not link back to B.

I marked the related links in the published topics in red, green, purple and yellow, so you can identify them in the stylized reltable on the right.

PDF topics with links from reltable
To take advantage of these linking mechanisms, the authors in your team have to agree on writing topics for reuse, organizing the cross-references in the reltable and using keys for inline references. I’ll be writing about linking via keys in a future post.
Happy DIT’ing!