- By Michele Marques, Lead Information Developer, ITSM

Some of you technical communicators have been working for years in XML and DITA. However, until recently, I wrote all of my product documentation in Adobe FrameMaker. Sure, you can write XML documents in FrameMaker. But I had been using "unstructured" mode, which doesn't enforce structure.

I just wrote a doc for an upcoming release using an XML editor and the DITA DTD. I was nervous starting out - after all, I've been using the same tools for years, and XML involves a new paradigm. But I also knew that this was a great time for me to move ahead in the new direction. I was about to reorganize the manual that I was working on.

Some things are easier in an XML authoring environment

Have you ever tried to reorganize a manual? Cutting and pasting between chapters isn't pretty - especially if you end up changing the hierarchy.

In XML, all my topics were separate files. All I had to do was edit (or create)  component and book maps. DITA uses component maps and book maps to determine the sequence and hierarchy of topics. Did I mention sequence and hierarchy? Each of the topics is a separate object in the component map; I can move the object up, down, left, and right. Within the topic, I have a title, and maybe one or more headings. The headings are relative to the topic title. But the overall hierarchy (which titles are chapter titles, which are heading1, which are heading2, and so on) is determined by the topic's placement in the hierarchy.

Actually, the titles aren't really chapter titles, heading1, and heading2 - that's a relic of paragraph styles from unstructured FrameMaker or Microsoft Word. Transforms give the visual appearance in the output (such as a PDF) that mark chapter titles and help readers differentiate between heading levels in the hierarchy.

But, enough of the technical digression. The point is that it was really easy to reorganize this material in the XML authoring environment!  If I had still been working in unstructured FrameMaker, I would be cutting and pasting.... and changing paragraph styles for the headings. And, somewhere along the line, I'd probably make a mistake or two, and maybe lose track of where I was in the hierarchy.

What about the pain?

OK, I didn't move into a fairytale when I started writing in XML. I'm new to this environment, so I'm still coming up to speed. As I learn the new tags and the new processes, I'm getting faster.

The most frustrating part was editing my index. I'm used to FrameMaker, where I have a tool (IXGEN) that will pull all of my index entries into one editable table - even sort them alphabetically. Then, I edit the entries in one place, and can push the changes back out to my FrameMaker files. And without this tool, I was able to generate an index, click with a special key combination on the index entry, and get to my index marker.

In the XML authoring environment, I can only see the generated index in my output (in this case, a PDF). I can see index entries as plain text within the XML topic files, but most of my index editing happens when I see the entire index together and realize that I need to modify some terms to be more consistent with others.

If any of you know about great tools for developing and editing index entries in XML topics, please let me know!

Was it worth the pain?

Yes! There are lots of benefits of working in small topic files. It's easier to reorganize material. And it's easier to divide parts of the document between writers. I'm looking forward to the next steps, when more people join me in this environment, and we can start sharing content.