Structured Document Formats, Part II
By Eric Armstrong on Feb 11, 2008
> Having written up that interesting discussion, what is your gut feeling at this time?
> If you had to make an authoring recommendation to a group to make life easier
> going forward, what would it be?
Well, I found myself going back and forth, as you can tell. That post reflected two weeks of thoughts that kept surfacing after a particularly stimulating discussion. This post is an attempt to come up with an answer.
My gut says that, in the ideal world:
- We need wysiwyg editing like Open Office, where you
never think about tags. We also need the capacity to edit in some form of Wiki text, to quickly
make small changes online without having to fire up a large desktop
application. (One day, when there is a seriously robust, cross-browser,
online DITA editor, the Wiki option may not be necessary. But that day
is quite a way off.)
- It is still necessary to add semantic tags, though,
(e.g. platform=, platform_version=7, product_version=3) so Open Office needs extending to present an interface for that.
- Given a wysiwyg editor that can do the right things, we need it to work on Wiki pages.
In the Open Office survey I took, they ask for feedback on which of 20 different things they should be working on. Two of the more interesting were "Open Office for blogging" and "Open Office for Wikis". The blogging tool already exists, and it works well. The only real problem for a Wiki tool is figuring out how launch Open Office when the user clicks "Edit". (They may be able to use Java Web Start for that--but it will have to be a separate copy of Open Office so it doesn't ask "Is it ok to print?", "Is it ok to save this file?" every time the user wants to do those things--or else Java Web Start will have to gain the ability to be used as a deployment vehicle, without having to accept its security sandbox to do so.)
- To allow reuse, Open Office needs extending for transclusion, and probably for conditional text, as well:
- For transclusion and variable substitution, we'll need href microtags that say "transclude the referent", rather than "display a link". (Note: The standard name is "microformats". But that term fails to connote their semantic import. So I call them "microtags".)
- For items tagged with conditional metadata, the user will need the ability to control colors, fonts, and text decorations. XMetaL is the exemplar for how it should be done.
- At that point, we have an industrial-strength "Wiki" that allows all of the encoding necessary for serious reuse.
- We should be able to automate the conversion to DITA topics,
but in the process, the document may well be split into
several subtopics. So we have to decide whether they should be put back together again when you're viewing the page and
you click "Edit". (We could, but what if it is the map you
really want to edit? On the other hand, if you get the map
and separate topics, it's harder to get a cohesive view
while you're editing, and harder to shift content between
topics in the document.)
- In any case, the conversion should probably be limited to
generic topics, for the foreseeable future. Information
typing to identify tasks and concepts helps to promote
reuse, but it adds many schema restrictions without actually guaranteeing reuse. (See more in the Specialization Notes, below.)
- In that sense, information typing is a lot like static
type declarations. They make some things easier, but
don't guarantee success. Just as testing is needed to assure success in a program, well-factored content is
needed to assure reuse in a topic.
- Enabling reuse then, comes down to the ability to easily edit and refactor topics. So the
editor/Wiki system needs to automate those operations as well. At a minimum, it needs to support topic renames, metadata renames, changes to metadata assignments (which affect all references, as well as the tagged entity), and topic splits. Whether other forms of refactoring can be supported remains to be determined (for example, topic joins).
- The ability to make global changes easily is also needed. So an interactive, list-driven, pattern-based global substitution tool is required. With such a tool, you have a list of things you're searching for. For each item, there are one or more possible replacements. When you find one, you choose which replacement to use, if any.
Ok. That's where we need to be. So where are we now, and what
can we use to get there? Here's what I see:
- To start, we need a good platform to build on. From a minimal initial system to a full-featured final system, many features need to be implemented. In some cases, tools need to be built to enable operations. (For example, a dependency-managed system for document builds--and/or a build-to-order delivery system--that can incorporate functional and procedural transforms, as well declarative XSL transforms. Those requirements suggest the need for a strong underlying architecture and a flexible, easily-extended programming environment like the one you get with Rake and (J)Ruby.
- Even with a Wiki-style front end, we would benefit from interacting with a CMS, instead of a Wiki database. There are 7 open source CMSes that need investigating--three Ruby-based, and four Java-based. (The Java-based candidates may be more mature, and since JRuby can talk to them, they may provide a more feature rich implementation to build on.) The major requirements are link management, webDAV capabilities, and a flexible, pluggable architecture that will allow for access-proxies at some point.
- It probably makes sense to come at the problem from both ends:
We'll lose the advantages of information typing with this system, but gain the benefits of collaborative authoring, with the lowest possible barriers to entry. Will the trade-off be worth it? Only time will tell.
- Use DITA where it's needed to minimize duplication. But voluntarily restrict usage to things that will migrate well: Generic topics rather than deeper specializations, version-number variables (but no name variables), a restricted set of metadata tags that are unlikely to change.
- Use Wiki documents wherever we can, for maximum collaboration.
- Continue to define and foster a merger of the two.
- In general, it may be that DITA led people slightly astray when it included the information types for concept, task, and reference. Those are extremely useful, but may not be totally necessary for everyone. (They're good examples of specialization, but perhaps they shouldn't be regarded as "the" way to do DITA.)
- Information typing does have benefits, though, Restricting task-oriented information to tasks does make them easier to read when you want to do something. Restricting concept to conceptual info makes them easier to reuse in different settings. Having a standard format for reference information makes things easier to find. So information types do help to make content more usable, primarily by restricting focus. In effect, the schema becomes a way to help automate the review/edit cycle, to keep content concise.
- But information typing also adds complexity. It requires more knowledge on the part of the writer and more powerful editors, both of which add up to "barriers to entry". Reducing those barriers means implementing a more user-friendly front end like a Wiki or desktop publishing system. But information created in those unfettered channels will not convert cleanly to the more restricted information types. So to the degree we want to enable collaboration, we probably need to eschew information typing--at least until better online editing systems emerge or until knowledge of the tagging structures become more widespread.
- To use the DITA specialization for SCORM-compliant training modules, on the other hand, we would need to use the Task and Concept types. That sort of thing could not be handled by a system that restricts itself to generic types. (The same for troubleshooting topics and other specializations.) So for the moment at least, a project that wants the benefits information-typing specializations will have to forgo the advantages of direct online editing--although other forms of collaboration could be enabled, as through a WebDAV-enabled CMS.
- Some forms of specialization still make sense, however. For example, if a "book" is an index map for something you might well want to print, a "library" would be an index map for a collection of books--something you might browse or submit to a batch processing job, but not something you would print as a single entity.
- In particular, I note that there are two major reasons for creating specializations. One reason is to remove tags so writers don't have to see them--a problem that goes away with either a front end that converts Open Office documents or Wiki text. The other reason is to define semantic tags. Semantic tags let you have a part-number list with part-numbers and descriptions, for example, instead of definition list. That lets you automate interactions with a database. And unlike microtags, the schema guarantees that all items in the list are in fact part numbers.
- There are in fact two ways to add semantic tags--either with metadata (microtags), or with specializations. The former is more flexible, the latter lets you define schema constraints. The former lets you do conditional processing, but requires Open Office extensions or a Wiki-text interface that has been extended for microtags (which need to be defined). The latter can be done with conversion rules, but still requires some form of microtagging: "If the list has a metadata tag that says "parts list", then convert all entries in the list to <part-number> instead of <dd>".)
- For an organization at the initial stages of defining a topic architecture, schema-constrained semantic specializations are a long way off. But metadata attributes are going to be needed pretty quickly, even if their use is constrained to relatively "invariant" environment characteristics, like version numbers. (Which suggests that Open Office will need the ability to specify and edit arbitrary attributes fairly quickly. Otherwise, a Wiki interface will be the only game in town.)