March 2006 Archives

Still on conrefs and dependencies.

I think I've just come up with a neat idea for handling conrefs in a mythical CMS (a reminder, we don't use a CMS, so I don't know if any CMS already does this or could do this).

When I create a conref in Topic B to an element in Topic A, the CMS includes metadata that indicates which version of Topic A I'm conref'ing from. A writer changes Topic A. I open Topic B for editing, and my CMS tells me, "Topic A/elementname has changed. Do you want to review the change or keep your existing content?" If I review it, I see the standard three pane merge tool view - my current topic with the old content, my topic with the new content, and Topic A. There I can choose to consume the content from Topic A (the conref is unchanged), reject it completely (losing all content for that element), or keep the previous version of the content (the element with the conref gets replaced by an element with the content from the earlier version of Topic A).

The second part of this would be reporting on conrefs. Before publishing, you run a report that notifies you of all the topics with conrefs to versions of topics that are not the most recent version and have not been resolved. This allows you to see at a glance conrefs that may no longer valid.

A neat idea or mad ravings of a hungry geek? You tell me.

XMetal implements a way of managing conrefs that I've heard a few people suggest as a method for getting around the dependency issues raised by conrefs. I think this is only half a solution, and causes other long term problems.

Here's the idea. When you want to conref an element from Topic A into Topic B, you open Topic A, copy the appropriate element into a new XML file, save that file somewhere (let's call this files SharedA.xml), and put a conref into both Topic A and Topic B. The way this is supposed to help is that when you are editing a file that has been marked as a shared file, you know other files depend on it, and you need to be careful about that dependency.

Nice idea, but look at the workflow of updates.

I'm writing Topic B. It has a conref to SharedA.xml. I need to make a change to that conref'd content. I know SharedA.xml is a special file so I need to check the dependencies. How do I do that? The only way I can think of is to do a full text search of my repository (whether that's a filesystem, SCMS, or CMS) for all references to SharedA.xml Fine. I do that and find out that Topic A and Topic B both depend on SharedA.xml. Now what do I do? I have three choices:

1. Remove the conref in Topic B and write new material, or create a new shared content file for my special text and change the conref
2. Make the change and notify the person responsible for Topic A
3. Make the change and check the content in Topic A myself

With option 1, you decrease reuse.

With option 2, you have no process to ensure Topic A is still correct. Who's now responsible to make sure Topic A is still right?

Option 3 implies that I'm skilled enough to know how to write Topic A myself. If I'm not, I might foul the whole thing up, and, thus, there's no way to ensure that my change is correct.

Knowing that the file is a special file is nice, but this group of shared files add some extra problems to project management.

1. None of these files are in ditamap files
2. Shared files don't expire
3. Ownership becomes muddled

Not having a file in a ditamap is just asking for trouble. The best way to manage DITA projects is to use ditamaps. They tell you what files are included in which projects and they include a bunch of metadata about each topic. Imagine you have 50 shared files. You cannot look at your ditamap(s) to figure out where those files are used, so you have to fall back to full text searching to determine whether a file is needed in a project or not.

Point 2 is very similar to point 1. Shared files will never be deleted because you don't know whether they are being used. So, your shared file repository will get bigger, and bigger, and bigger, until your writers can't find anything in it.

Point 3 is more minor, but could be an issue for some companies. If more than one writer is depending on the content in a shared file, how do you determine ownership, and, as a consequence of ownership, who is responsible for maintaining and editing a shared file?

A better solution is to use dependency checking. When a Topic A is opened, the writer is notified that an element in Topic A is conref'd by Topic B. The writer is then clearly responsible for ensuring that the content in Topic A and Topic B makes sense after editing, and no extra non-managed files are created.

Sadly, I don't think there are any non-CMS tools for doing this kind of dependency checking, nor can I think of an easy way to create one.

I applaud XMetal for trying to find a solution to this problem, but I hope that other vendors don't follow their lead in this case.

I attended the DITA 2006 conference in Raleigh, NC, last week. Overall, it was a very good conference. Good networking opportunities, some really good meetings with vendors, some really nice presentations.

One of the more interesting things that I noticed was the number of attendees that were surprised, perhaps astounded, that IBM doesn't use a CMS for their content.

I think I've covered this before here, but I think traditional content management systems, which are usually designed to work with binary files that represent documents, need to change to support a topic based system like DITA. CMS vendors need to learn SCMS like Perforce, ClearCase, etc. When you have more than 2,000 XML files, and a large team of writers without strict boundaries, diff and merge, build and test, dependency analysis, branching, and other common SCMS functions are vitally important.

SiberLogic seems to understand that software documentation and software development are moving closer together in their needs. However, I heard some rumblings from the crowd that SiberSafe, SiberLogic's CMS tool, may not yet be ready for prime time. It does have one feature that I think is vital for DITA CMS tools - "Where Used".

When a writer opens a topic for editing, they need to know the side effects of the changes they make. When you are writing code, the build will fail if you screw up a dependency. In DITA, your dependencies can fail in two ways

1. Just like code, you can break a dependency.
2. Unlike code, you can change the context of an element that makes a dependent topic invalid

I went to a Golden State Warriors game the other night, and, since the game was so bad, started paying more attention to the fans than I normally do.

The loudest people were the insulters, several were sitting right in front of me. They call players names, insult them for their play, etc. I wish those people could be thrown out. It's a bloody game, people! They are playing for your entertainment. You should appreciate it.

The other person that stood out for me sat right behind me. She made sex noises throughout the game. The Warriors would be making a move, and they'd be heading down courts and she'd quietly moan, "Oh god, oh god, oh god ....", of course followed by a loud exclamation when they either made a basket or didn't, like this, "Oh god, oh god, oh god ... Yes! Yes! Yes!".

It made for an odd night. It was like sitting between a group of loud-mouthed jerks and the soundtrack from a porn.

One of the challenges I've found in working with DITA is managing the build process, specifically my ant build files. Since ant build files are in XML, I've been using my XML editors (either oXygen or Stylus Studio) to work on them. Although they help a bit, since ant build files don't have a schema or DTD, they don't help too much.

I started using emacs, and that was easier, mostly because I am more familiar with emacs as a text editor than either of my XML tools. Then I thought I'd take a look at Eclipse. I'm glad I did.

Eclipse takes a little while to set up, but once you've created a project, it's very easy to work with. The biggest advantage of working in Eclipse when working with DITA projects is that you can easily find all your build targets and edit them. DITA 1.0.1 has multiple XML files that store build targets - build.xml, pretargets.xml and conductor.xml. When you are trying to debug the build process, it's very hard to figure out which file has which target. Eclipse helps you with that. Open build.xml, and it lists, in outline form, all the targets available, including those that are in imported files. The imported targets are clearly marked, and you can double-click on them to open that file at the appropriate target.

Since Eclipse understand ant build files, editing them is also much easier. Tasks, parameters (variables? I get confused with ant syntax), and macros are all available from the auto-complete menus. That alone has saved me hours of debug time.

Another advantage is that there is an oXygen plug-in for Eclipse, so if you own oXygen, you can do some pretty sophisticated editing and debugging without every leaving Eclipse.

I still need to figure out how to kick off the ant builds from within Eclipse, but the time I've saved by using Eclipse has been a real help.

This is cool. AppExchange is really a very powerful part of Salesforce, and now there's an AppExchange Toolkit for Eclipse. Add that to the PHP and Ruby toolkits, and the AppExchange platform is really growing to meet just about any extension needs you could have.

There's a great opinion article on the Neiman Watchdog by past NSA director Lt. General William E. Odom called
Iraq through the prism of Vietnam.

As General Odom points out, don't go too far when drawing comparisons between the two conflicts, but we shouldn't ignore them, either.

Unlike what happened in Vietnam, I believe that it is possible to end our invasion of Iraq in a positive manner, but to do that we have to commit to working with Iraq for decades to come. Walking out and leaving the American trained forces in place isn't good enough. We need to help Iraq toward stability, and once Iraq is there, we need to help Iraq create a self-regulating government so that it won't be continually threatened by coups or political overthrows.

The invasion was wrong. But we shouldn't ignore the reality that we have destroyed this country. Because of that, it's our duty as a country to do the right thing now. We can never make up for invading, but hopefully we won't leave behind an unstable country that will slip into ruin.

While riding on the light rail this morning, I wrote a brilliant essay on Zen. The only problem is that I didn't have anything to write it on. It's seems so easy to write when I don't have anything to write on. Maybe that's why everyone thinks they can be a writer.

I was walking to the ferry building yesterday and I saw a couple in their 30's walking the other way. The man was wearing a grey sweatshirt from French Connection UK. It was a simple grey hoodie. Nothing special. Across the chest was written, in big letters, FCUK. That hoodie, without the logo, was probably about $30. With the logo it was probably $80. So, this guy paid extra to advertise for a company. That's not too unusual (stupid, but it's a stupidity that a lot of people are afflicted by), but the bit I couldn't get out of my head is that he's walking around in something he paid too much for with a juvenile play on words. It would have been cool if it said "FUCK", that would have shown something. But FCUK is just ... I mean, what, did he see the sweatshirt and say to himself, "Hee hee hee, it almost says fuck". A college student? Sure, but why would a grown up wear something like that? It just made no sense to me.

There's a report out today about "Ex-gay" programs. Take a look at
SFGate's article

The logic of the people that are trying to change the desires of other people is astounding.

Wait, just in case you were wondering, I think this kind of program is insane. Sexual attraction changes over time, but, if you are only attracted to people of the same sex, that's unlikely to change through "therapy".

Okay, so here's an example of why I think this is so insane. Alan Chambers, an ex-gay who is president of Exodus International, in Orlando, which acts as an umbrella to about 250 ex-gay groups worldwide, said

"If people like me exist," Chambers said, "then they weren't born like this (gay). Change is possible or could be possible."

Not to trivialize Alan's life, or to be too politically incorrect, but this is like a person who was temporarily paralyzed saying to a life-long paraplegic, "I used to be stuck in a wheelchair, but now I'm not. So, you can change, too!".

Many people change their sexual feelings over time. That doesn't mean that people make a choice to be gay or straight. Regardless of your sexual orientation, think back - did you ever choose to be the way you are?

Now, let's get into the most important statistic of the study.

Almost 90 percent of the people studied (these people had gone through therapy to become "ex-gay"), reported long term harm from the therapy.

If that number is true, these people should be shut down, perhaps even put into prison. Imagine if a pseudo-religion like Scientology had a study about them with similar numbers. We'd be up in arms.