April 2005 Archives

After listening to a lot of questions people have had for the speakers on DITA, I've come to the conclusion that project management is a tricky issue for a lot of writers. Although I haven't yet brought a DITA project to its conclusion, I have managed projects with similar organization. Based on that experience, I'm going to lay out how I think a DITA project should be managed. Please let me know if you agree or disagree using comments so that everyone can see your feedback.

Before I really get into that issue, though, I want to define what a document is, and why we need to be careful when we use the term.

Traditionally, when writing, you are focused on the output, the deliverable, whether it's a white paper, an article, or a book, is what we call the document. DITA is different, though. DITA is based on the idea that you create a bunch of topics, that are then assembled into a deliverable, like a PDF or a group of HTML files, or a Windows help file. What then, when we are talking about a DITA project, do we mean by a document? Is it the XML topic file or is it the deliverable? For the purposes of this note, I'll use document to mean the deliverable, not the XML file. I encourage everyone, when they are talking about a system like I'm describing here to stop calling their source files documents.

A document created using DITA typically begins as many XML files. This is because DITA is a topic based system. A topic is the smallest piece of information that can stand on its own. DITA has three base specializations of the topic: task, concept, and reference. When you are writing documentation, you're likely to have many different tasks, some concepts to impart, and some reference material. Each task, concept, and reference area, will be in a unique file.

In a traditional desktop publishing (DTP) system like FrameMaker, since you are writing a document, not just a topic, you have one file, or, taking advantage of FrameMaker's book paradigm, you might have a group of files that are managed using a FrameMaker book.

When you are writing and publishing using DTP, the DTP tool helps you manage the files and how the files interact. Using a FrameMaker book as an example, FrameMaker controls the order of the files, how the document will look when it's printed, what the boilerplate pages look like, linking between pieces of information, etc. So, you manage your project using your DTP tool.

Although some DTP tools can manage DITA projects, normally when you manage a DITA project, you'll need to approach it in a different way. At the heart of DITA project management are map files. Map files may or may not be associated with a deliverable (or document, to use the above terminology), but the reverse should always be true. In other words, when you identify a deliverable, you should always have one map file that is the controlling map file for that project. The map file may, probably should, be composed of smaller map files that are all brought together using conrefs.

The advantage of having a master map file for a project is that you define a path through your project. In other words, if you are reviewing the document (remember, that's the composed output of the project) and you notice that one of your topics isn't in the table of contents, you don't have to rack your brain or search the filesystem to figure out where to add the mapping information, you know you just need to go to that master map file. If you use conrefs to merge multiple map files into the master map file, the master map file leads you downward to the other map files.

More later ....

According to the Seattle Times, the US government has decided to stop issuing its yearly international terrorism report. This is the report that gives lawmakers and citizens a statistical view on the number of incidents of international terrorism.

Last year, the report had to be redone when it was found that the numbers were unreported. Some people think that was done to help President Bush get re-elected by providing proof that terrorism had gone down. Once the report had been rewritten, it showed that more terrorism happened in 2003 than any previous year.

This year, according to a source that talked with the Times, there were 625 incidents. That's more than 3 times the number in last year's report.

No wonder the Bush administration doesn't want this report released.

At the opening talk, JoAnn Hackos talked about information as Legos. We create the information, but the reader can put it together however they want. One of the audience members said that you can't do that. People, when they build their own information set from topics, put together things that aren't usable, or that are wrong. He said they don't build Lego sculptures, they built mush.

I agree and I don't agree. People can build crap with information topics, but they can also build something that appears to me to be crap, but is perfect for them.

Sticking to the Lego theme, customizable document sets are like a pre-packaged set of Lego's, for example, like a Star Wars X-Wing kit. When you first buy the set, you follow the directions, and you get an X-Wing. But then you pull it apart and use the pieces to create something else, either your own version of a spaceship, or something completely different. I may think your spaceship looks crappy compared to the X-Wing, but you don't, you think it looks cool. My brother might think it's cool, too, and want to build his own version of it. You don't have instructions for how to do that, but he can look at your ship to make his own. He'll probably make his own changes to that, too. So now, from this set of Legos, we've got three different ships, one for each of us, and each of us is happy with the ship we have.

When I create an information set, I'm organizing the information using information maps, tables of contents, etc., just like the Lego designer built the X-Wing set. Unlike most people, you might read it in the order I intend it to be read in. But even if you read it that way, in your own head, you tear it apart and make it your own. More than likely when you read, you search, you use the table of contents and index, you follow cross-references, and you wind up with a completely different document than the one I wrote. That's customization.

Allowing you to make that customization persistent for your later use, or to share with other users, could be incredibly powerful.

Danny O'Brien, of LifeHack fame, talks about how many productive computer professionals have "secret scripts" to do web scraping and RSS creation. Why do they do that? They do it to get the information in the way they want it. Information customization fits that need. These power users aren't the only ones that could benefit from this kind of information customization. When we make it easy for people to find and customize the information we author, we'll be taking a huge step forward.

I'm at the Center for Information Development Management (CIDM) Content Management conference the next couple of days. I'll be posting some of my thoughts throughout the week.