Everyday IA Episode 7: The Information Architecture Checklist
Everyday IA is a podcast series designed to guide users through the Information Architecture Blueprint™ Template Toolkit: DITA Edition.
Information architecture documentation can, very quickly, become unweildy. The IA Checklist provides a simple way to quickly track down key decisions and data from the architecture development process.
Transcript
Alison Yildorok: You're listening to episode seven of the DITA Strategies podcast series, Everyday IA. This series is designed for folks who've 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 Alison Yildorok. Welcome to episode seven 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 Information Architecture Checklist to capture the IA decision summary for easy reference.
If this is your first time listening, then 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: Amber’s here to explain how you can use the Information Architecture Checklist to capture the IA decision summary for easy reference. So Amber, I'm just going to let you go ahead and jump in.
Amber Swope: Awesome. Thanks so much, Allison. So, in the other podcasts, if you had a chance to listen to them, I've talked about how I use these other tools, these diagrams and worksheets, to be able to take a focused look at different aspects of the information architecture to understand what our requirements are, to understand what the structure is, and to understand for instance, if you’re using XML and you’re using the DITA standard, which element you would actually use.
Well, the value of each of those independent tools and templates is that, that deep focus. But when you need to remember what you decided, I can tell you that you don't want to have to go and find, “Oh, well, where did I write that down? And which tool did I use for that?”
And this is the whole purpose of the IA Checklist. What we want is a summary that's a quick reference for you. So, if somebody asked you a question, you can, really quickly, be able to answer it without having to go and look at your in-depth documentation. So, the checklist provides that high-level summary.
I’m going to walk through the key points that, if you are developing information architecture for DITA, the Darwin Information Typing Architecture XML implementation, that I would capture. Then I’ll also add a couple of the other points, if you are using some other format or standard, that you might also want to consider.
So, the first thing you want to do is put the date at the top, because we want to know when this checklist was last updated.
The other thing I like to, personally, have is, actually, a checklist, a place, where I can indicate, with a check mark, what I have actually addressed. And then I can quickly see the items that, maybe, I still need to do some more research in order to make a decision.
So, I'm a big fan of laying it out so that I have three columns. The first column is where I can put my check marks. The second column identifies the item about which I'm making my decision. And then the third column is the decision itself.
So, for instance, if you are using XML, the first thing I want to know is, you know, what are the, the high-level structures that we’re using? If you're using DITA, well, what kind of map might you be using? For instance, in DITA there are bookmaps and standard maps, there are learning types of maps, there are, potentially, specialized maps that you have for your content.
I would want to, first of all, indicate, “Yes. I have made that decision.” I would check the box and then I would be filling in, “Oh, we’re using book maps for this purpose. And we’re using standard maps for that purpose. Or we’re only using standard maps for everything.”
Then, again, in the DITA category, which topics are we using? Well DITA has an out-of-the-box set of topics. Are you using all of them? Are you using a subset of them? Are you using general topic? And are you using it for very specific purposes? This is your opportunity to make that summary and write it down so that you have the information you need at your fingertips.
I don't typically include all the elements that I'm using in my content model in the checklist, simply because that’s a larger collection of information. I will put the name of the document or the file name of that spreadsheet, if you’re using the content model sheet, so that you say, “Oh, yeah, um, here’s the document that you need, that can answer your question.”
Although I wouldn't list every single element, I would identify some of the key items of, um, element usage. For example, my IA checklist includes important information about how I use elements.
So, one of the things I want to be really clear about are, what’s a quick summary of the requirement? So, for instance, if you have to support 508 Compliance, which is a requirement that means that you have to have content that's available for folks that are visually impaired, that means that you have to have some accessibility support. Well, DITA has some elements that you might use. If you're using another standard, you might use something else. Write it down—what are the ways that you will be supporting accessibility in your content?
Another item is, do you have special types of tables? For instance, some folks have parts tables, some folks have specifications tables. What are the requirements there? And how are you meeting them? Do you have special requirements around how you present images? And when I mean images, I mean diagrams, photographs, illustrations. Whatever you have to support, make a summary of what it is you're supporting and how you're doing it. Videos, multi-media files—same thing.
Then some navigation aids. Do you need to include index entries, search keywords, or other types of metadata that are important for you to note for the purpose of navigation?
Another category of architectural decisions that I want to track are, how I'm supporting reuse. So, for instance, in DITA there are a number of mechanisms that we can use that come out-of-the-box with the standard.
First one I would want to know is, are we using conditions in any way? If so, what are the conditions? What are their values? And how are we supporting them?
Next up would be, what type of element reuse level are we using? Are we using content references? If so, for what? Key references? If so, for what? Content key references? If so, for what? I know it sounds repetitive, but you've made these decisions as you developed your architectural support. It’s time to summarize them and know what, how you're using this information.
In the area of reuse, also indicate what topics you are expecting to reuse by their category. For instance, if you are expecting to reuse your glossary topics, or you have common safety information, or you have common learning objectives, and you were going to use the entire topic, make a note of that.
Maybe you have common information that you collect together in a map and you’re going to pull that same map in, in multiple places. Note that down, because when someone comes to you and says, “Hey, um, I can’t remember what I'm supposed to reuse.” You don't want to have to go paging through a long manual or any type of other documentation. You want to be able to, very quickly, answer their questions.
Another important part of information architecture is your metadata. What metadata are you going to support? So, first thing to look at is, from the XML standard, what metadata do you plan to use? For example, the bookmap construct has a significant amount of metadata. Any of the topics can have a significant amount of metadata. What do you want to track at the map level? What do you want to track at the topic level in the XML itself?
It may be that you put nothing in the XML because you're using a component content management system, a CCMS, that handles all that for you. Well, then you want to say, “Oh, okay. Which CCMS are we using? And how does it store this information? Is it at the topic level? The map level? Is it on images? Is it managed at smaller units?” Depending on the technology you’re using, different vendors manage this information in different ways.
One of the other things to look at is, does this metadata and the content it supports, does it map back to the data model? If so, identify that data model and the last date it was updated, because other systems are always evolving and the teams that support them are continuing to update that support. And we want to make sure that, if you based your content model and the associated metadata on decisions from a data model, that you are keeping information current with the progress that they are making with their support.
The other thing that I'm always interested in, particularly from the metadata point of view, is, for what elements are we generating IDs? A lot of times, you can configure your system to automatically generate those IDs. This is really important, particularly if you're expecting to content reference content, you have to have an ID on that element or you cannot access it and reference it.
The next thing in the architecture that I, I want to track is, what type of deliverable support we have. So, we should have a look at what we had in our deliverable structure diagrams and in our deliverable worksheet and get a summary here to say, “Oh, okay. What output types are we supporting? PDF? HTML? XML? XHTML?” There's any number of, of, formats that you might need to support. But it would be nice to have it all listed in one place.
And then I want to know, by deliverable type, what is the overall structure? So, for instance, you are supporting folks that are creating manuals. Do they have a front cover? Do they have notices? Table of contents? If so, how many levels? Do they have chapters? Appendices? Back covers? Footers? Headers? And just a quick summary of those patterns.
Um, for instance, if you have online health systems, are they per product? Are they per component? Do they use context-sensitive IDs at the page level? At the element level? Or the field level? What exactly do you need to know when someone says, “Oh, what do you support?” That's what you want to put in this area. And you want to list each of your different deliverables and what that support might be.
The last category of information that I include in my checklist is around technology. When you design the information architecture, you’re designing the structure around how content will be built. Well, most folks don't go into notepad to build your content. They work with other tools. And you want to be very aware of how your architectural decisions are supported in the toolset that your content creators are using.
And, so, we want to have a quick summary of how we are supporting the authors when they create the content in the tools that they are using. So, for instance, if you have folks that are writing content in DITA, well, they're going to be using an XML authoring tool, or more than one.
First of all, identify what tools that they are using. And identify what user role will be using that tool vs. another tool and what kind of templates you’re going to provide. In DITA, the most obvious template categories are maps and topics.
So, for instance, if you have, expect folks to use bookmaps for manuals, well, then we would say, “Oh, we expect them to use bookmaps for manuals. And here's the name of the template.”
If we expect them to use standard maps for other deliverables, or for chapters, or other structures, we would want to stay, “And this is the template name.” And if you have different templates for different tools, list them out with their template name and a brief description of why you have more than one of them.
The same for your topics. When I help folks design this type of support, I typically have more than one task template. So, for instance, there's the task template that has just the basics, which would be the title, maybe a short description, maybe a context, and a set of steps. And then, because the task is the most rigorously structured topic type, I include a starter task topic template, which has all the information and all the elements that can be used, as an example of their usage, because the order is important and sometimes it's hard for folks to get started.
So, one of the things to think about is, how many topics to have, which tool to be used in, and if you have different, multiple templates with same topic type, indicate why.
And last, but not least, it's always helpful if you can understand where things are being stored. So, if you are working with a system that has a folder structure, whether it be a source control system, a wiki, or a CCMS that has a photo view, identify the folder structure and explain where the important pieces of content will be.
For instance, if you are expecting folks to reuse content, you need to be really clear about where that content is stored. That type of information should be outlined in your checklist, so that when someone says, “Hey, I need to find the reusable glossary entries for x product,” you don't have to go and open a browser and go hunt for that information. You can very quickly answer these questions.
My checklist, when I fill it out, usually runs about two pages or single page, front and back. I do print this out. It's not something that, um, everyone prints out. But I like to print it out and have it hanging next to my desk so that, when I’ve got questions, I don’t have to go and open my computer and find it. Um, I can very quickly find the answers that I need.
Unfortunately, as the architecture evolves, it means that I have to update it. And sometimes I’ll reprint it and other times I’ll just manually put a checkmark on there and make, you know, handwritten notes.
So, I’ve described what’s in my Information Architecture Checklist for DITA. If you are using another XML standard, take the parts that I just described and adapt the checklist to meet your needs. If you're using HTML, maybe you’re using Markdown, or maybe you’re using other ways of creating your content, if you are creating an information architecture to help folks create structured content, at least summarize your decisions and have them available to you. It might be different subsets of decisions, but I can’t emphasize this enough, because folks will ask you questions and you don't want to spend time hunting for that information.
So, write it down to summarize the key decisions that you made and, sometimes, why you made them, so that you have that information at your fingertips when you need it, so that you can be a great support person for the people who are using your architecture.
AY: And with that we conclude this episode of Everyday IA. Thank you for listening. Be sure to visit us at ditastrategies.com and follow us 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]
To utilize Amber Swope's expert information architecture assistance consider booking 10 or 25 hours of coaching.
