Author: saprentice

Topic: Roundtable discussion on file naming conventions.

Speaker: All (notes – courtesy of Eric Armstrong, also posted below in case the sun.com site goes away)

---

SVDIG Notes: AirHelp and DITA File Names

Notes from the March meeting of the Silicon Valley DITA Interest Group, covering AirHelp and DITA naming conventions.

AirHelp

When Scott Prentice took a look at the Adobe AIR programming language for Flash-based applications, he liked it. He said, “It would be pretty easy to make a help system GUI with this.” So he did. The result was a nice little 2-pane window that displays a TOC or index list in the navigation pane, and the selected topic in the content pane.

Once he did that, the next step was to set up a processor to put DITA topics into the help engine. So he did that, too. The process has one manual step, at the moment. But he’s working to automate that. Once he does, the processor will become a plugin for the Open Toolkit, so that generating AirHelp will be as simple as specifying the right option when invoking the Open Toolkit.

One of the advantages of the system is that Adobe AIR programs are platform- and browser-neutral. So you don’t have to worry about things behaving differently depending on the browser and that platform it’s running on.

Another major advantage is that the program “calls home” to see if newer content is available. So it’s easy to make sure that users have the most complete and up-to-date information available.

Finally, users can add comments to their pages. Their comments are stored on the server, and remain intact when the page is updated. (The fact that they’re stored on the server makes it possible to one day build a system for content review. Although the AirHelp system currently doesn’t have that capability, Scott has built such systems before.)
As the author of the original DITA plugin for FrameMaker, Scott has now created a complete end-to-end system for authoring, delivering, and updating content, using DITA and the Adobe AIR system.

For more, see http://www.leximation.com/airhelp/

DITA File Naming Conventions

The topic for the March meeting was a roundtable discussion centered on the question, “What naming conventions do you use for DITA files and the directories they’re contained in?” There were three basic mechanisms. One was using prefixes like “c_” to identify concepts and other information types. A second was organizing topics into separate directories for different topic types.

The third was a completely different strategy that came as a complete surprise to pretty much everyone present. That one was offered by none other than Scott Prentice. It’s a strategy of “non-organization” (at least with respect to file names). But he cleverly makes it work by utilizing DITA to its fullest. To find out more, read on!

Strategy #1: Directory Organization

John Gibb represented the most popular option in this category: Different directories for concepts, tasks, and references, with maps in the outer directory.

Gary McCue had a slightly different strategy, with one folder for each “domain” (roughly equivalent to a product).

Most everyone had a separate directory for shared content. Ernst Allen used “common” for the name of the directory, and “share” for the name of symlinks that point to from other directories. (If your maps aren’t at the topmost level, symlinks are needed because DITA maps can only reference laterally and downward, but not outward.)

Strategy #2: Filename Prefixes

The second option was to use for filename prefixes to keep information types separated. John Gibb represented this strategy, in addition to the directory strategy. he mentioned that when they started, they weren’t sure which strategy they were going to settle on, so they wanted to keep their options open.

Of course, it often happens that different topics are needed for the same kind of thing, because they don’t share enough information to make a single topic practical. In that case, metadata needs to be included in the filename to keep them separated. So you might wind up with a task called t_install_productX_platformY.dita, for example.

But once you do that, it becomes that much more difficult to keep all of your metadata in sync–especially when the metadata changes. Because there are four things to keep synchronized in a file-based system:

• Metadata in the topic (which can be used for searching, especially if the topics migrate to a CMS)
• Metadata in the topicref (because a topic won’t be excluded unless it is there, but you’ll wind up with a title and no content if the metadata in the topic causes the content to be excluded)
• Metadata in the filename
• The metadata-containing filename in the topicref.

That’s a lot to take care of when things change. But the “Un-Strategy” advocated by Scott Prentice provides a solution…

Strategy 3: The “Un-Strategy”

Surprisingly, Scott Prentice totally punted on the subject of filenames. “Why bother with them?”, he reasoned. Put all of your topics in one directory, and give them all unique ID numbers. Treat the whole thing as one big CMS.

So how on earth do you find things? “Use the DITA maps as your navigation tools”, was his reply. And to really find things, “Put all your topics into a single map and use that to generate help. That gives you an index and the ability to search.”

Gary McCue’s group had a similar strategy, where they generated a PDF that contained topic titles and short descriptions. But Scott’s solution has a certain elegance. It eliminates file naming as an issue, and uses DITA capabilities for generating help to get CMS-like indexing and searching.

All in all, it’s a solution worth considering.