There’s been a lot of talk on the DITA Technical Committee lately about the perception that DITA is too complex. It’s got me thinking. I think the reason people think DITA is too complex is that there are a lot of features in DITA that are not there in other basic XML languages – conrefs, keyrefs, reltabels, scope\/format\/type, etc., and it’s incredibly hard to learn all of them at once. I also think that while DITA maps allow a lot of flexibility, all that flexibility carries a considerable complexity cost. I mean, the <topicref> element has 38 attributes. 38! And I think the human mind looks at all those attributes and just shuts down. But if you strip away all the bells and whistles, I don’t think it’s that hard.<\/p>\n
So. DITA 101. From zero to DITA in 15 minutes. What follows isn’t an in-depth discussion of everything you could ever possibly do with DITA, but hopefully it provides a basic overview of what DITA is<\/em>.\u00a0Prerequisites for this class: a basic understanding of XML as a format for documentation. Ready? Here we go.<\/p>\n DITA, at its core, is is two basic concepts.<\/p>\n A publication represented as a Microsoft Word document is a great big hunk of text and tables and pictures and whatnot; if you want to reuse part of it in another document, you copy and paste it to that other document. But now if you want to change something in that reused hunk, you have to change it in all the places it’s used. That’s not very efficient.<\/p>\n For that and other reasons, XML-based content authoring was born, where you still author one great bug hunk of text, but now you have tools and systems that can take that big hunk and break it down into chunks that can be reused\u00a0directly<\/em>\u00a0in other publications. Change the content once, and those changes automatically happen everywhere that chunk is used. Plus, now you’re authoring semantically rich content. Instead of saying, “these set of words here? That’s a person’s name, and we make people’s names bold and yellow and blinking,” the author just has to say, “that’s a person’s name.” The color and font and blinky-ness of a peoples’ names is somebody else’s job, and can all be automated. Which is great! But. It introduces a whole new<\/em>\u00a0set of problems. XML uses document types, and content using one document type can’t be used with content of another document type. Reusable chunks are often coded in a way that puts restrictions on exactly how and where they can be reused. And anybody who’s been in this industry for a while can talk your ear off about something called Entity Hell. Trust me, you don’t want to know.<\/p>\n So, unto the breach, comes DITA. At the core of DITA are two simple but radical concepts.<\/p>\n That’s it. Author in small chunks, and author in a way that can be easily shared.\u00a0Got it? Good. So first: authoring in small chunks. Let’s talk about topics.<\/p>\n It’s a bit of a mind-flip for authors, but a liberating one. Forget context. Forget document flow. All you, the author, have to worry about is documenting one specific thing<\/em>. A topic is basically a traditional document, but instead of being burst into chunks, it is<\/em>\u00a0a small chunk, meant to be combined with others. But you don’t have to care about that. All you have to care about is documenting one thing<\/em>. Let other people worry about how use that information.<\/p>\n There are three main topic types in core DITA:<\/p>\n There are others – glossary entry, strict task (like task, but meaner<\/em>), and any number of custom topic types, but these are the basics.<\/p>\n All topics have the same basic structure. They may use different tag names to describe this structure, but the structure is always the same, for every DITA topic, everywhere, forever. That structure is:<\/p>\n All topics use the same basic set of tags: paragraphs, lists, links, quotes, pre-formatted regions, phrases, etc. – that are specialized<\/em>\u00a0into more meaningful tags. For example, the DITA <b> tag (‘bold’) is a specialization of <ph> (‘phrase’). The DITA standard specifies a relatively small set of fundamental tags, and most of those tags will be familiar to anybody who’s ever dealt with XML or HTML content. A topic type may use a completely custom set of tags, but every tag in every DITA topic is based on that core set<\/em>. Always. Forever. Every time. And that’s why you can use any DITA document with any DITA publication. Any given DITA processor may not know how to deal with <process>, but if <process> is a specialization of <ol> (‘ordered list’), any DITA processor will handle it gracefully.<\/p>\n So. That’s topics. Once I have a bunch of topics, how do I create a publication? Well, for that, we have to talk about maps.<\/p>\n A DITA map is a collection of <topicref> elements that describe the structure of a publication.<\/p>\n Pretty simple, right? You simply structure the <topicref> elements in a map to match the Table of Contents for your publication. Any DITA-aware processor can take a map, find those topics, perform various transformations, and produce some sort of publication. Just like in topics, there’s a core set of tags that can be specialized for more specific uses, but unlike topic, most tags in every map anywhere is some specialization of a single tag: <topicref><\/em>.<\/p>\n There are<\/em>\u00a0other types of tags that are common in maps. You can use <topicmeta> within a <topicref> to provide metadata and processing behavior for the referenced content. But for the most part, when you’re dealing with a map, you’re dealing with <topicrefs>.<\/p>\n Of course, there’s lots more to it than this. As I said, the <topicref> element alone has 38 attributes that can be used to control how the ultimate publication is rendered. But hopefully this gives you a basic understanding of the major building blocks of DITA.<\/p>\n","protected":false},"excerpt":{"rendered":" There’s been a lot of talk on the DITA Technical Committee lately about the perception that DITA is too complex. It’s got me thinking. I think the reason people think DITA is too complex is that there are a lot … Continue reading \n
\n
\n
\n
<topic id=\"topic\">\r\n <title>Example Topic<title>\r\n <body>\r\n <p>Hello World!<\/p>\r\n <\/body>\r\n<\/topic><\/pre>\n
<map>\r\n <title>My Publication<\/title>\r\n <topicref href=\"HelloWorld.dita\">\r\n <topicref href=\"SubTopic.dita\"\/>\r\n <\/topicref>\r\n <topicref href=\"SomeOtherTopic.dita\"\/>\r\n<\/map><\/pre>\n
<bookmap> <!-- I'm a specialization of <map> -->\r\n <title>I'm a Book!<\/title>\r\n <bookmeta\/> <!-- I'm a <topicmeta>. Ignore me for now. -->\r\n <frontmatter> <!-- But I'm a topicref. -->\r\n <booklists> <!-- Me too! -->\r\n <toc\/> <!-- I'm... wait, am I? I am?! Cool. -->\r\n <\/booklists>\r\n <\/frontmatter>\r\n <part href=\"part1.dita\"> <!-- Uh-huh! -->\r\n <chapter href=\"part1chap1.dita\"\/> <!-- Don't forget me! -->\r\n <\/part>\r\n <backmatter> <!-- You guessed it! -->\r\n <booklists> <!-- Remember me? -->\r\n <indexlist\/> <!-- Boo-yah. -->\r\n <\/booklists>\r\n <\/backmater>\r\n<\/bookmap><\/pre>\n