Slide: (Cover) Let's Talk About DITA Maps

Greetings and I hope you're enjoying ConVEx. I really wish I could be there in person with you.
I hope you're ready to talk about DITA maps and that, by the end, you love them as much as we do.

Slide: About Me

I’m Liz Fraley. And the main thing I think you should know about me is that I love creating connections with people and sharing knowledge. I have a BS in Computer Science, and an MA and BA in English. I read over 200 books, thousands of articles, blogs, news, and mailing lists, every year. I sit on the boards of and volunteer for 3 non-profits, one of which I started. I'm always searching for new ways to increase the knowledge of the professionals in the communities I serve.

For me, it's all about empowerment. I may not know the answer, but I always know where to get it -- or at least how to find it. Think of me like the librarian behind the research desk at the library. Presentations like this are my way of bringing people together to share knowledge, ask questions, and enable each other.

The link in the lower left hand corner http://bit.ly/convex2022-fraley is the public event page for this presentation. These slides are on that page as are a growing list of resources about style guides. We know that you want to learn and so do we. So be sure to visit that page. While this video won't change, that page will always be current.

Slide: Who We Are

For those of you who don’t know us, we are Arbortext specialists from California. We have been a part of the PTC channel program for over 15 years and we have always focused on Arbortext. Our experience goes back even farther since we were implementers and users of the arbortext products long before. We are pretty passionate about the suite and what it can do for our customers. We have seen it first hand with some amazing transformations for tech pub groups after adopting Arbortext and best practices and we have lived it as well. We have even written a few books to help others gain knowledge and confidence.

Slide: I'm here to talk about maps, not present about them

I'm not here to present about maps. I'm here to talk about them.

Whenever I present, I like to talk with an audience. I learn through discussion and I usually learn as much from an audience as they learn from me. At the very least, I always get ideas for new pathways to travel. More importantly, I am being relevant to you. After all, a presentation isn't about the presenter, it's about the audience. So please, talk back, share your stories. I promise I want to hear them.

Slide: Quick Poll

First a quick poll: How do you use maps? One of these ways? Other ways?

Definitions:

• Deliverable: A book, pdf, set of html pages, something that represents a content deliverable. Like a quickstart guide, user manual, etc
• Division: This is any grouping of topics under a Head-Level, to use old terminology: Head 1, Head 2, Head 3, or other division of the deliverable
• Key Management: This includes conrefs, conkeyrefs, links out to warehouse files --- I'm not covering this, it's a deeper topic
• Other: Anything at all…

Slide: Do you create the map first or the topics first

Do you create maps first or do you create the topics first? If you think of them as deliverables, do you create the map first or the topics first? I guess the question is really - do you outline?

Slide: Let's talk about maps

OK. Let's talk about maps.

Slide: Most [*] equate maps with deliverables

Most people, most companies, even most vendors equate maps with deliverables. You can see this in the screenshots that I took of almost everybody's website.

From XMLMind https://www.xmlmind.com/tutorials/DITA/index.html
"2. About Topics and maps": The "contents of a DITA document are specified using a topic map"

From OxygenXML https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Maps/c_Working_with_Map_Files.html
"Purpose of ditamap files": "You can create as many maps as you need ... create one map for your [brand1] Owner's Manual, another [for brand2] Owner's Manual"

From Structured Authoring Blog http://structuredauthoring.net/xml/readings/10_dita_maps.html
"Structure of a DITA Map": "each topic you want to include within the deliverable"

From Adobe https://help.adobe.com/en_US/framemaker/using/using-framemaker/user-guide/frm_structauthdita_sd_dita-maps.html
"DITA Maps." "A DITA map allows you to … create output"

They all equate topic maps with deliverables, implying that a map is for defining what your output is going to be.

And that carries over: Most people think a MAP=DELIVERABLE. It's common throughout the community and accidentally, it creates a link in the mind of a new DITA user that a map equals deliverable, and that's something that's really hard to correct later.

Although a new DITA writer may do more here and there, have another map that they use, it's usually one of those things that they inherited or that someone else set up. Doing more with maps, thinking maps can be more, it just never comes to fruition in the minds of new DITA writers. Maps are not a tool they ever really come to employ on their own.

And the thing is, once you start seeing it, you can't unsee it and you start to see it everywhere.

Slide: Yes, a map can represent a deliverable.

All that said, yes, a map can represent a deliverable. But it doesn't have to represent a deliverable.

You might have different maps for different output types, one for PDF, one for HTML, one for compiled help.

You might have different maps that employ different formatting or different profiles, or to include or exclude information based on the deliverable. For example, you might have one that defines what goes to customers and another one that includes more because it's released internally. You might use profiling or other profiled information to define what might be contained in a map, or produced from it. And then in that case, you are seeing a 1-to-1 relationship between a map and a deliverable product.

But defining deliverables is just one of the things a map can do.

Slide: Structure Maps organize the order and hierarchy of a deliverable's division.

Here at Single-Sourcing Solutions, we also talk about something that we call a structure map. A structure map is something that organizes the hierarchy of a deliverable's division. What's a division? Well, it took me years to realize that no one outside of the Arbortext community uses that term. A division is a significant hierarchical, structural part of a deliverable. Generally, it means you have maps in maps

For example, if you have a book with chapters, each chapter would be considered a division and that division might have its own map. A chapter is a division of a book. If you have a book that has multiple parts, then the parts are divisions. Each part can include a number of chapters, a lower level division because chapters contain a number of topics.

You might have more levels as well, such as volumes and parts. We're talking significant structural hierarchical divisions in a deliverable. That's why we call them divisions. Topics are not necessarily divisions. When I talk about structures and divisions, this is what I mean.

The example shown comes from our training material. We have a book about lavender that we use.

There's a part about culinary lavender. There's a part about horticultural and agricultural lavender, information to help you grow and sustain it. There's a whole section on its uses as biofuel and other things. Each one of these are conceptually significantly different from each other. So each relevant topic would be sorted into the corresponding deliverable division.

And, in our world, that means each division might be its own map. The culinary map groups all of the recipes together. This grouping helps the user of the documentation product, as well as the person writing the document to group things together and to be able to work on a division rather than the book as a whole. It helps us sort and bucket things together in a logical way.

The structure map is not a deliverable, but it represents a part of that deliverable, a significantly structural part.

And that's what we call a structure map.

Slide: Procedures are sets of tasks (and maybe some concepts and reference topics), which makes them perfect candidates for maps.

One of the other ways we typically talk about using maps is to support procedures. Here at Single-Sourcing Solutions, we differentiate between procedures (or processes) and tasks. A procedure is a set of tasks and maybe some concepts and reference topics. It's a grouping of things that all together provide enough information to complete the greater process.

A procedure, a process, something at that level. It's multiple things, kind of like the division idea, but a little lower down in the hierarchical chain.

For example, if you're setting up your Nintendo Switch, you have to add family members, you have to set up the Internet, you have to create your Nintendo account. There's a bunch of things you have to do when you set up your Nintendo Switch. I know this because I recently had to set up one for my mom.

The setup isn't complete until all the subtasks are done. In that case, we would not consider set up as a task, but rather as a procedure. You need to add a member. You need to create an account. These are all the topics (concepts, tasks, and reference information) related to this procedure. And the map groups them all together. And a user needs to walk through it all, they walk through it in order, just like the map specifies. The procedural map is actually pretty handy. It's very useful because it lets you group things together — everything can travel around together. It's a grouping of tasks that might go in the user guide, but it might go also in the Quick Start guide. It might go in a reference guide that says.

A procedure map contains all the things that need to be done and all of the things to understand—-and it's all grouped together. You don't have to forget one. A procedure map is a great way to group stuff together so it can travel together and you don't have to remember all the pieces. Take the work out of your head and put it somewhere where it's encapsulated. Let the map work for you.

As an aside, we've found that this kind of map structure provides a way to address the expert user versus the novice user. DITA has the notion of the mini-toc at the start of every chapter. Well, a procedure map functions similarly, grouping lower level topics, which means I can manufacture content and create a mini-toc for the procedure without the chapter scaffolding. In the context of a procedure, the mini-toc serves to list all the tasks that need doing, which might be all the expert user needs—-They just need a reminder of all the steps they have to go through. The list of topics serves as that reminder. I get multiple-audience support because I'm using advanced techniques available to me through DITA and the tool support.

Procedure maps can be pretty powerful.

Slide: Key management maps encapsulate keys so you can define override and fall back behavior.

Next most obvious map type is the key management map. Key management maps encapsulate keys so you can define an override fallback behavior. Typically you either define keys at the top level or you make a map that has all your keys in it and insert the key definition map into your deliverable map. Then the values for those keys get pushed down through the topics in that deliverable.

This starts to get complicated when you have multiple key maps that represent different values for substitution. The most obvious case for keymaps and substitutions is the support of OEM docs because you can take all those keys, you can put them in a key map, you can visualize all the keys together in one place, and you can pull that map in to a deliverable map and use them. It's really easy to conceptualize by splitting that stuff up. Maps are great for simplifying dimensionality of behavior.

For example — and it's frequently recommended (although not us)— if you have multiple key definitions and you want to change the values from deliverable to deliverable, you make duplicate maps. You change the values and include both maps in your deliverable. TO change which values push down into the content, you change the order of the maps in the tree.

One of the things we do and that I'll come to later is a better way to handle this overall process, but let's stick to what most people do.

Put one on top and put the other below. The values in the first one (the top one) are the ones that push through. If you want the other one, you switch the order. You just reorder the maps in order to change how the substitutions happen.

We don't do that. We don't even recommend doing that because then you have all the keys are defined and it's a lot harder to visualize. And if you've got a key management tool, you'll see all the definitions at the same time and it's really hard to know you're getting the right one.

Also, with all key maps included, it's easy to have errors creep in. Say you create a new variable, you add it to the map that you were using to test with, that map you had defined at the top level, and you put that key down into the topics. And then you forget to put the redefinition in the other key maps that were also included or in that one map that wasn't included.

Generally, when you do things this way, when you make a new map, you clone an old one. And if they're not all in sync, you won't have all the definitions. It's really easy to screw up.

I'll talk about a better way to do this at the end; It comes out of our experience and exuberance from using maps.

Slide: Subject Maps organize groups of things that are related, like all the topics necessary to completely document that new feature.

All right, so the next type is what we call the subject map. A Subject map organizes groups of related things, like all the topics necessary to completely document a new feature. A subject map is not a deliverable and is never used in one.

For example, these are all the things you have to do to fully document the new feature. I've got to have this and I need these. I need some reference topics. I need some concept topics. I need this procedure. It's going to go with that chapter in that book and this chapter in this book. And I need this procedure, which is for maintenance or tracking or troubleshooting.

A subject map links all the topics that you know you're going to have to write. They're all related to this feature implementation and use by the customer. It helps keep track of them. You don't have to wonder if you have done them all? Has everything gotten done?

And when you are done, you can create a quick deliverable just of these topics to send this to your subject matter expert and say, do I have all the high level concepts you want me to cover ? And then later, they can look at it without having to look at the deliverable where they're possibly all spread out across a single, or even multiple deliverables, for user experience reasons.

After all, the topics go with multiple outputs, multiple deliverables, multiple audiences. One goes to internal, one goes to external, one goes to an OEM, and one will get an extra level of detail and some will get less, but you need to keep track of everything.

A subject map is something that is created simply to help you do your job better. This is all just my vocabulary to help get the point across really right. Think of this as something, as a way to help you just keep track of things.

There are any number of ways you can use a subject map.

Slide: Maintenance maps are temporary, throwaway maps that serve a specific purpose at a specific point in time.

A Maintenance map builds on the idea of the subject map.

A maintenance map is a temporary map that serves a specific purpose at a specific point in time. You might keep it; you might throw it away when you're done. You would create a maintenance map if you wanted to gather all the topics on a specific subject to make your maintenance job easier later on, like when a feature changes. How many topics do you have to touch to make sure that change percolates throughout? A maintenance map would group all the things that were written about a particular topic so you don't have to go searching for them.

I would likely also create a maintenance map to simplify the SME review process. Say I wanted to show someone what was in the old one and what was in the new one without requiring them to read change markup. If I wanted to provide a side-by-side synoptic alignment of the text, I would make a maintenance map that has the structure: old version, new version, old version, new version, old version, new version.

Then I'd create a quick PDF to circulate that has the old version on the left page and the new version on the right page, all synched up. I would do it in PDF, because usually that's the easy way. I just want them to review. I don't need them to do anything else.

To give you a better idea, let's think about legal publishing in Canada. In Canada, the laws are published in both English and French, French on the left, English on the right, and you want it to be lined up, all the way down, and you don't want the sentences in different languages to get out of sync. For something like that, I'd make a maintenance map that contains only the content that I want that subject matter expert to review. So they don't have to see everything or go hunting around.

The SME wouldn't have to guess at what the change bar indicates (pulling out the old document, pulling out the new document, and laying them side by side). I could take the work out of it for them, improving the odds that they do the review quickly (and don't dread having to do all that extra work).

And once the review is done, so is the map's usefulness. A maintenance map is a throwaway map. Why would I keep that? Once they've been through it, I'm done with it. I'll throw that map away and do something else the next time. It's a temporary throwaway map that serves a specific purpose for a specific point in time.

Think of a maintenance map as one of those things where you're trying to keep track of something and you just want to serve that specific purpose for the length of time it's needed. Maintenance maps as review maps are very useful in this way. A maintenance map is anything that makes it easier for you to do your job.

Slide: Maintenance maps can be for anything that makes it easier for you to do your job.

For example, I did a presentation last year on warehouse topics, and I created a whole set of warehouse topics for indexing because I want the index to be consistent from book to book, and across the entire set of books. I want to use the same vocabulary over and over again. I don't want to mess up and have one with an S and one that doesn't have the S. I want a standard spelling and to catch when I've spelled it or ordered it differently. Because we're all that consistency, right?

So I made a map: The one on the left. The entire contents of the book are the warehouse topics full of index terms. Each warehouse file is a chapter in the book. So you don't see anything in the chapters because there's nothing there because it's just index terms. Right? But the index gets built with everything and that's what I'm interested in.

It doesn't matter because the map is only there for me. It's a showcase for the warehouse topics. I can put whatever I want in it. I'm not going to include anything that isn't an index term outside of the warehouse. And when I publish this index terms maintenance map, I get a comprehensive index for all the terms across all the books. It was just one of those things that was super easy to put together. And its purpose is simply as a QA tool for me. And I can look at all the index terms together. I can find inconsistencies.

A maintenance map can be anything that helps you check or group or gather something. Maintenance maps are insanely useful.

Slide: Who uses the reltable and who still uses inline links?

Who uses the reltable and who's still using inline links? Because reltables are map based and inline links are not. If you're not making use of the reltable, you're not making full use of your maps.

Slide: Hello, reltable, Salesforce is done with inline linking.

In fact, back in 2014, Salesforce did a presentation for us where they talked about how they are done with inline linking. They moved everything to the reltable.

Why? Just look at these pictures, The inline links are repetitive. And all the links go to the same few pages.

Account ID, Account Partner, AccountFromID, AccountToID. Over and over. All those links go to the same pages. Over and over. Why are there three of them in the span in that little bit of space? Right.

There are multiple things Salesforce found when they started digging into the analytics and there are multiple reasons why they chose to abandon the inline link.

Inline linking has an overhead for writers that is nontrivial. Maintenance of inline links are a headache.

In addition, inline links are distracting to readers. People will see a link and they'll click on it, ignoring the rest of the page. And they'll click and click and click and click, and end up somewhere far away. They'll forget where they started and they can't get back.

There are a lot of issues. And if you're interested, we do have the video you can watch.

But if you move to the reltable, you're making more use of your maps. That's what the maps are for. So take a look at the reltable again. If you're not using them now, you should still consider getting rid of inline linking, that's all I'm going to say about that.

Slide: Great things happen when you use multiple maps in concert.

You can either reorder maps to change how substitutions happen or you can use hierarchy, which is what I do

This is the time to talk about fall back behavior and overriding.

Maps are great for simplifying the dimensionality of fall back behavior and supporting OEM docs

Now that you know the basic types, even better things happen when you combine maps together, when you use multiple maps, different kinds of maps, in concert.

For example, let's talk about creating a structure map and combining it with a deliverable map and a key management map

It's the OEM example.

First, we make a structure map. The structure map represents what this typical deliverable looks like for anybody, for us, for OEMs, for whoever. Then, you make a key map that has that all the keys required by the topics in the structure map depend on. And that key map gets inserted into the structure map. A structure map, not a deliverable map. That low level key map has default values, default values that I should never see when I'm looking at an OEM variation of the deliverable derived from the structure map.

This is important because you can't see spaces, you can't see blanks. You won't necessarily notice if something in a sentence is reasonable, but it was supposed to be substituted for an OEM. If you haven't seen, be sure to attend Mike McGinnis's presentation, "Rebranding with DITA and Super Bookmaps," Track #2 at 3:20 pm. He talks in depth about how they are making extreme use of structure and key maps, and how they work together to create OEM documentation.

Earlier, when I talked about the key management maps, I mentioned that most people make multiple key maps and they use ordering, moving one above the other to change the value substitutions in a deliverable. However, if you change the way you're thinking and instead use this method which uses the power of maps and the inherent DITA overriding mechanism to reduce your problem space and make the entire thing easier to visualize and construct.

We use the structure map and the key map together, putting the structure map with the key map. Then we create a deliverable map that represents the deliverable for OEM #1. The deliverable map includes the structure map (with its keys) but it also includes any redefinitions of keys that are relevant to this deliverable, here at the top level.

We're reducing the dimensionality of the problem. It's kind of like going to the store, right? When we go to the store, we're not actually thinking in three dimensions. We're thinking in two dimensions and adding the third on top: We think of going to the store—it's across town, and then we add on the idea that we need 20 minutes to get over there. We're thinking in two dimensions and adding the third. We're flattening first the where (the X, Y), and then we're adding the Z (time), and we're really only ever thinking two dimensions at any given time.

Stephen Hawking said he could think in four dimensions but I'm not him. I don't even approach him.

So to make things easier for me to conceptualize, I will use the same concept and reduce the problem space. The low level has the book structure and the keys required in it. Then I can add a new dimension, the OEM dimension, and think only of the deliverable itself and the substitutions, the override values in the higher level. In addition, because the keys are isolated at a high level and they don't depend on ordering to make them work, it's a lot easier to see and spot where key failed, especially if you're employing the default keys at the lowest level, things that are in all caps or turn red or something else that will be obvious when you're doing QA after the fact.

We're reducing the problem space by a dimension by using a structure map, a keys map, and a deliverable map together. And we can reduce that problem space making everything a lot easier to conceptualize, implement, and produce.

Slide: Join me in doing more with maps and don't forget to tell me what you discover!

I'll encourage you to think about how you can use maps and their strengths in multiple ways, alone or together, to get something that makes your job easier to do and your deliverable more friendly to your audience.

I know that I'm always finding new, more, better ways to use maps. There was at least one that I didn't include here but that I have found really useful so far. Maybe I'll talk about that one in the future. It will certainly end up on the page for this session https://bit.ly/fraley-maps

The video won't update, but the landing page will. So be sure and keep an eye on it.

And if you're finding ways that you use maps, please tell me. I want to hear about it. I am always looking for more and interesting ways to use maps.

Slide: Resources

This session's website landing page https://bit.ly/convex2022-fraley

Using Warehouse Files to Improve the Overall Findability of Your DITA Content (2020) https://bit.ly/fraley-warehouse

How to Identify DITA Topic Types (like a pro) (2018) https://bit.ly/fraley-ditapro

Get your [bleep] together...with DITA maps (Tracy Baker, 2017) https://bit.ly/baker-maps

Working with DITA Maps in Arbortext (2015) https://bit.ly/fraley-axmaps

Herding Tigers – How Salesforce Let Go of Inline Links (2014) https://bit.ly/berry-linking

Slide: Closing with Contact Information

Be sure to connect with me on LinkedIn and when you're ready to do more with maps, when you're ready to move from being a beginning DITA writer to intermediate and advanced, Single-Sourcing Solutions is here for you.

Email: liz.fraley@single-sourcing.com
LinkedIn: https://lizfraley.me