Everyday IA Episode 6: The Deliverable Structure Diagram
Everyday IA is a podcast series designed to guide users through the Information Architecture Blueprint™ Template Toolkit: DITA Edition.
In the sixth episode of our Everyday IA podcast series, Amber Swope explains how you can use the Deliverable Structure Diagram, a component of the Information Architecture Blueprint™ Toolkit, to define the structure of each deliverable type, capture visual analysis, and convey the structure of information.
Transcript
Alison Yildorok: You're listening to the sixth episode of the DITA Strategies podcast series, Everyday IA. This series is designed for folks who have been tasked with developing or contributing to the architecture of their organization's content. The intent of this series is to guide folks through the fundamental tasks required to develop their information architecture using the templates from the Information Architecture BlueprintTM Toolkit. Let's get started.
[Music]
AY: Hi, everyone, I'm Allison Yildorok. Welcome to episode six of the DITA Strategies podcast series Everyday IA. Today, DITA Specialist, Information Architect, and President of DITA Strategies, Amber Swope, will be talking about how to use the Deliverable Structure Diagram to define the structure of each deliverable type.
If this is your first time listening, thanks for joining us. You can find this and previous episodes, as well as more about DITA strategies, Information Architecture, and our products and services at ditastrategies.com. Now, without further ado, let's get into today's episode.
[Music]
AY: So, I have Amber here today to explain how and why you may want to use the Deliverable Structure Diagram. Amber, take it away.
Amber Swope: Thanks, Alison. So, in the previous podcast, which I hope you listened to, I talk about understanding what the purpose of each deliverable is and what kind of content is going into it. And if you've done your analysis with the Content:Deliverable Matrix, you'll have a really good sense of all the different types of information that we're seeing in these deliverables.
Well, I'm a big fan of visually portraying my findings and it really helps me with my analysis. It also helps me communicate information architecture principles to folks that, quite frankly, know nothing about information architecture, nor do they want to. I find that the, you know, a picture is worth a thousand words, really is applicable when trying to communicate with folks about, “Hey, what should be in our deliverables?”
So, I have created a series of Vizio diagrams that allow me to visually represent the structure of these deliverables. And I've gone down the route of color coding the different items—other folks might use different shapes, things like that.
But the things that I want to capture are, first of all, what is the collection of units? What are the individual units? Within these units, what items convey structure? What items identify content? And what items specify metadata?
Once I have that understanding, I want to get more clarity on how often these items appear. I want to know if they're optional, but you can only have one; I want to know if they’re optional and any number; whether they’re required and there’s at least one; or that they’re required and only one.
And then I also care about whether or not the items are a collection, which you might bring in together, or whether you have to make a choice—you can have this or you can have that.
The things I go and looked for, for instance, when I look at a book, I identify, “Oh, it has a cover. And on the cover, we see we have a title, we have subtitles, we have product name, we have product version, we have the company logo.” What are all those pieces that we see on the cover?
And then, when we go into the book, what do we see? We see that there is front matter. And what I mean by front matter is that information that's at the beginning of a book that usually has a different numbering scheme and appears prior to the table of contents.
Well, what's there? Most folks have some type of a legal notices or copyrights page. And they may have additional information—maybe there is a list of revision history information or other information that, again, comes prior to the table of contents. And if you have a table of contents, that’s important to know. How many levels? Then is there any other information that appears here? Do you have a list of figures? A list of tables? Do you have glossary? What, what is in the front of your deliverable prior to, what I think of as, the meat—where we get in and we provide actual content? And we usually see something that has chapter numbering or even collections of chapters, might be called part, Part I, Part II, things like that.
And then, once you have chapters, you may also have appendices. And the difference with those is that they usually have a different purpose—they are for being referenced. And they’re visually distinct, in that, again, the numbering pattern on the pages might change. And the numbering, so, for the chapter, so if it's chapter 1, 2, 3, 4, appendices is usually, are alphabetically numbered—A, B, C, D.
And then we have back matter. Do you have back matter? If so, what's in it? Do you have a glossary? Do you have an index? What else is back at the end of each of these deliverables that we need to consider? A lot of the times, this information is truly reference information and, ideally, we could generate it.
So, in the case of a book, those are the kinds of things I would expect to see. For a course, what would I expect to see? So, for the course, we, we start off with the introduction and then usually there's an overview of the modules in the course.
And then, within each module, what might we find? Well, we might, again, find more learning objectives, maybe a pre-assessment quiz. Then we would see the, the full information. “Oh, here's, here's the information you need to know. Here’s how the task would work in order to, to perform a task. Here is an exercise that allows us to practice the task.” Or maybe you watch a video or you go out and do a lab. Then you have a quiz that says, “Oh, you—” allows you as a user to know that you've actually learned the skills that you need. And that, that pattern would repeat itself over and over for each module. And that the overall course, as the deliverable, would have this repeatable pattern within it.
Another example might be if your deliverable is a report for Professional Services that you completed. Well, in theory, you wouldn't have to go and create, recreate everything every time. A lot of Professional Service engagements are built around a methodology. We would expect, then, that we would see, in the structure for the report, the backbone of that structure would map to the methodology. And then, in the methodology, we would expect to see certain types of information. And, at the end of a Professional Services report, we usually see an area for next steps or additional services that would help the customer be effective.
If we look at what types of deliverables Tech Support or Customer Support has, well, in that case, they might have troubleshooting information. So, if you are delivering troubleshooting, the first thing you want, you would have in your structure is a statement of what the issue might be. And then maybe a description of the symptoms. And then maybe there are some tasks that you could perform to, to verify that, “Yeah. This is the right issue that you're having.”
And then there might be a process or series of steps or tasks that you would perform, that would, at the end of each one, would be, “Well, did that fix your problem?”
“Yes.”
“Did that fix your problem?” And if the answer is no, you move onto the next one.
These are structures and, notice, I'm not, I’m not mentioning exact words or the information that might be in that content—whether it be text, or visual, um, graphics, or video, or audio files—but how they come together and how they are organized so that you put together the right collection of information to meet your user’s needs.
As I mentioned, when I draw these diagrams—and my, and the toolkit has a series of diagrams in there—I do this with color. I want to be able to, at a glance, be able to see, “What's the highest level unit? Oh, there’s where we actually have text. Oh, look at that, we have metadata.”
And I'll talk a little bit about what kinds of metadata I expect to see on deliverables. I might expect to see the description of what it is, a release date, a deliverable type, any search keywords that need to be there. If it's specific to a given product or if it's a book, I might expect a book number to be there. If it's something that's been released before, maybe there's a revision ID. I also might expect some copyright information or other information that might be used when someone is either looking to search for, “Oh, when was this released?” They might use the copyright date and information, want to know who it's registered to if you're going out onto a site, that is, where multiple companies provide information. It really depends on what the deliverable is to depend on what kind of metadata might need to go with it.
For instance, in the case of a course, let's say that it is, I'll go back to my example, from the previous podcast, of a driving ed course for Oregon drivers who wanted to pass the course to be able to successfully complete the license, license exam and the driving test for the Oregon license, driver's license for automobiles. Well, that structure is, is a modular structure. And if I were to diagram that, it would be the course and then there would be an introduction that explains, “Oh, you know, hey, this is what you’re going to learn here.” And then, the outline of the course. And then, within each of the modules, I would expect there to be learning objectives, conceptual information, maybe some reference information, and a little quiz, followed by more information, and then maybe some assessment at the end of each of the modules, followed, at the end, with a practice test.
It doesn't matter which of those modules covers road signs and which of them cover safe driving tips. The structure of the content is the same. And so, what we want to do is be really clear about what that is. And like I said, again, with metadata, it's super important to know which metadata you need for each of the deliverables.
If you're going to go look for a course, well, having a course number could be helpful, particularly, if you are in a college situation where you know that it's Biology 101. Well, I, sure as heck, want to know that, that number and it needs to be there as metadata.
In the driver ed example, it's more important that you understand which of the license types that you're trying to, to prepare for the test. The test for a motorcycle or truck driver’s license is different than the test for driving an automobile. And so, we want to make that information be there for search and retrieval.
Now, in my templates, what I do is, I have a separate diagram for each deliverable type. And, as I mentioned, I would indicate, not just what the structure is, but how many of each of these items might we have?
So, in the case of the learning information for the course, I would have, the collection is the course. And then I would have a series of modules. And, to me, those modules are structures that reference and contain other content and that they might each have their own metadata. And so, I might even have one diagram for the course and then a separate diagram for each of the, for the module to say, “Oh, within a module, I expect to have this type of information and this type of a structure.”
Let’s say that the course also, that it's instructor-led training. So, let's say that there is an instructor-led training version of this course—that means that the instructor will also have a guide. Well, in theory, the overall structure of the instructor’s guide should correspond to the structure for the course, but there might be additional information in there. Maybe, for each of the modules, there's a area there that has “Oh, and here are our instructor notes.” Maybe it comes at the beginning so they know, “Oh, in order to successfully deliver this course, you need to know these things, you have to have this information, and you need to be able to play these videos, etc.”
And for folks that have a wide variety of deliverables, you can have a significant number of these diagrams. I've seen folks with, you know, twenty or more, because they are producing a large number of deliverables and they want to understand what the, the structure of each one of them should be, each by type.
How will you know that you have the right number of diagrams? So, if you are using the Deliverable Analysis Worksheet, then the easy answer is that you would have one, at least one diagram for each of the deliverables that you analyzed with your worksheet. And what's nice about having both of them is, when you go to talk to your stakeholders, you can either walk them through the text version or you can simply show them the picture and say, “Hey, this is the diagram. This is what we think the pattern is for this information. Is it correct? Do you agree that every course needs to have an introduction and present the overall structure and that, at the end, that we should always have a final exam? Yes, or no?” And your stakeholders would be able to say, “Oh, yes, that’s exactly what we should have.” Or, “No, there are times when it's not appropriate for us to have a final exam.” Or they might say, “Wow, you know, we actually should have an exam right up front so that we can understand if the student needs all these modules.” Because, if they're in an environment that allows the student to have a subset of the modules, well then, why present all of them if the student already knows the information?
I'm a big fan of going through and making, basically, a catalog of the types of content that, you know, the types of deliverables that you have and being really clear that, “Oh, when I go and look at a user guide, or I go and look at a troubleshooting knowledge base entry, or I go and look at an online help system, I will expect to find these items, these content items in it, and that they will be in this order, and then this metadata will be here.”
This visual representation can be really helpful when you're negotiating with multiple stakeholders to get some standardization in place. A lot of times, if your company has grown over time and that, there will be some discrepancies and differences in the deliverables that different people have created. Or they might have been asked, by their product owners, to do something different.
Another use case where having this visual representation is very helpful as a negotiating tool is when a company acquires another company. If you are the acquired company, it's the, you know, folks are going to be saying “Well, what do you have? Here's what we have.” And it's really helpful to walk in and say, “Well, this is what we have. Can we negotiate on this? When you say user guide, are we saying the same thing?” And conversely, if you're the company that acquires the other company, it's nice to be able to open that discussion with an example of your structure and to say, “Hey, let's, let's look at this and see how close we are.”
And I like it also because it takes it to the abstract level and allows us to see what's beneath the content, beneath the formatting, beneath the bold, the italics, the different fonts, and the different colors, and the different logos, and all the branding that marketing gives you—that you can strip all that away and look at what you actually are creating, how you are organizing it, and what you're actually delivering to your users.
For me, the diagram is not an option. It is a mandatory part of my analysis so that I can also capture, “Okay, this is what we agreed upon. We said that user guides will always have this information in them and not other information.” Or “Help systems will always have this information, but not this other stuff.”
In summary, I highly recommend that you make a visual representation of the structure of your content to both help facilitate the discussion with your stakeholders to come to agreement, but then also to record what it is you agreed upon so that, a year from now, when someone says, “Well, I don’t know why the template has this in it,” you can come back and say, “Well, because, according to the discussions in July of 2018, here's what we said we all wanted to produce. If what you're saying now is that that is not appropriate, then we have a place to start our discussions and our negotiations to either validate that the structure we identified is still relevant or to say, ‘Oh, let’s update it because, perhaps, our user’s needs have changed.’”
So, although the templates in the Information Architecture BlueprintTM are Vizio diagrams, if you do not have access to Vizio, there are other ways that you can capture this visual analysis. Any diagraming tool, whether it be a mind mapping tool or even a diagram, a workflow diagram that you put together in word, those mechanisms can help you convey the structure of your information.
AY: All right, and that concludes this episode of Everyday IA. Thank you for listening. Be sure to visit us at ditastrategies.com and follow DITA Strategies on Twitter, LinkedIn, and Facebook to join the conversation and stay updated on helpful articles, podcast, events, and other resources. We hope you'll join us on the next episode.
[Music]
Interested in the toolkit?
