Smart approach to document profiling (DocBook)

Today I visited a seminar on single-sourcing at Philosoft. We had 2 presentations:

• An overview of MadCap Flare (presented as an alternative to AuthorIT, Help-n-Manual, and in many aspects to FrameMaker).
• A round-up of how single-source documents are created at Philosoft.

The round-up was most valuable.

First, Philosoft writers create genuine single-source documents, where each document is built from content pieces stored in a common database. Unfortunately, they did not quite explain which types of content pieces they have and how they arrived to these types. However, they promised to share this info on their website soon.

Second, I really liked Philosoft's approach to profiling output documents in their DocBook environment. They suggest 3 criteria for profiling:

• Subject for document's subject, e.g. a certain software product, hardware item, or person's role, etc.
• Aspect for document's type, e.g. user's manual, administrator's guide, product reference, etc.
• Profile for subject's or aspect's flavor, e.g. software's version for a certain OS, hardware's model for a certain customer, etc.

These 3 criteria make up a unique combination for each document. The guys say this trinity is quite enough for all profiling needs. Besides, knowing the 3 criteria for each output document makes drafting more focused.

Technically, they use 3 native DocBook attributes to tag conditional elements in a single-source database:

• conformance for the subject
• userlevel for the aspect
• condition for the profile

As for myself, by now I've been maintaining a database with one source XML document for each product's documentation set ("subject" criterion). Where needed, my XML sources are tagged with condition attributes to define the output document's type ("aspect" criterion). For all flavors (e.g. product version) I've been using XML entities ("profile" criterion).

Now I'm thinking of trying the 3-criteria approach and probably fine-splitting my per-product XML sources into pieces to make up a joined database.