DITA from the trenches

Here are my notes from the February Central Texas DITA Users Group meeting. You can join the Yahoo Group for our user group at http://groups.yahoo.com/group/ctdug/. There were about sixteen of us in attendance. Kristen Thomas spoke to us about converting the AIX doc set to DITA from SGML. Don descriptively called it “DITA from the trenches.”

Here’s her bio:

Kristin Thomas is the information architect for IBM’s AIX information center. She has written installation and security documentation for AIX, and she also oversaw the conversion of the AIX library to DITA and topics. Before working on AIX, Kristin wrote Linux documentation in IBM’s Linux Technology Center for open source projects, such as the Linux Standard Base, openCryptoki, and the IBM Carrier Grade Open Framework reference implementation. Kristin has been with IBM since 2000, writing documentation for IBM’s Software Group and Systems and Technology Group. She is a 2000 graduate of the Masters of Arts in Technical Communication program at Texas Tech University.

We talked about some administrative items first with Don Day. Next month they’re hoping to schedule France Baril, who has done a lot of DITA work and may be in Austin next month. Don asked for ideas for topics future meetings. One person requested a Task modeler sample talk, which is Eclipse plug-in. it’s a tool that lets you quickly create DITA maps and generate stub content for a prototype build, including support for major map structures like hierarchies (like tables of contents) and relationship tables (like related links) and the base DITA topic types (concept, task, reference). Download it from http://www.alphaworks.ibm.com/tech/taskmodeler. It’s available under an evaluation license, but you do need to register with alphaworks before downloading.

We had some discussion about an animal mascot to represent our user’s group. I vote for some Darwin-related animal but the finch with the specialized beak is already taken as is an iguana.

Don also let us know about the new dita.xml.org web site.

Here are my notes from Kristen’s talk — not really cohesive or comprehensive, but it represents the parts I took away. I’m hoping to link to her slides once she posts them. (Updated to add the link, but you have to be a member of the CTDUG Yahoo Group for access.) All in all a very informative talk. I always like it when you can ask questions of the people really using the technology.

IBM’s AIX docs were originally in SGML, and went from 13421 to 18062 files by going to topic-based DITA authoring (XML-based). They call their deliverables information units, not books or help. They use an Eclipse-based authoring environment.

Users loved that they can customized info to their needs, that they can find things consistently in the same place as other info units, and so on.

Workflow: writer creates pre-conversion out line, editor helps them by reviewing it and helping them “type” the info, meaning, look at the sections and determine whether they belong in a concept, reference, or task topic.With the outline, they’d track topic IDs and filenames for use later with an Excel spreadsheet, to help with broken links and tracking and so on. Next they’d run a conversion script on the existing content, and then fix everything that was broken. Quite the undertaking it sounds like.

It helps you to have meaningful IDs on things, although I asked about any nomenclature scheme for naming IDs, and they don’t have one. Typically it’s just the topic title. I would suppose that starting the file name with con_ for concept, ref_ for reference, and tsk_ for a task might help you sort in the file system. And yes, they only use a file system with relative paths, not a heavy-duty content management system. IBM uses flat file systems for keeping their DITA content and uses the map for metadata. So a writer might have 300 flat files in one folder for one information unit, and only have the file system tools and the ditamap for searching through or ordering files.

With DITA, you manage links in maps, no cross linking between files is allowed/recommended.

IBM uses Xenu, a web-based link checker, post-processing. After a build is complete, reports with lists of broken links are sent out.

The editor reviewed outline before doing conversion, checking topic typing checks, flow, and so on. Kristen said this review was VERY helpful – don’t underestimate the value of your editors for their ability to step back and get the big picture when you’re buried in the details.

There was some pre-migration work, such as clean up tags, outline, check duplicates of information.

For users – information units are grouped by category. Here’s the URL to their content which mostly contains DITA topics. http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp

They found that task topics were the most difficult for writers to write up, and I would agree. The name of the <cmd> tag was hard for writers to remember at first (DITA uses <step><cmd>Click this thing</cmd></step> for each number step in a list… yes, some writers would get around it by just doing numbered lists in a generic topic file rather than a task file.

They had some content they didn’t convert, such as man pages, but hope to move towards a specialization of ref topic that would describe a man page.

Their search engine brings up the text within a <shortdesc> tag in addition to the <title> text, so it’s important to put in <shortdesc> info.

Don showed us a Syrna app uses XSLT for styling, so you could tell it to display the shortdesc and title when working in a DITA map file.

Lessons learned