The DITA Open Toolkit download site includes several demo specializations that few people discover and use. In this webinar, DITA maven, Don Day, will use these examples to highlight the role of information modelling that led to each specialization. Don will highlight the key points of how each specialization was created, or how semantics were introduced into the specialization, and a whole lot more.
5. Information Modeling
from the Demo DITA*
Specializations
Don Day,
Contelligence Group LLC
* The Darwin Information Typing Architecture, an OASIS XML
markup standard
6. Lead-up: High Octane Content
• Adobe TechComm Central blog post:
http://blogs.adobe.com/techcomm/2014/06/high-octane-
documents-june-12-dita-model-webinar.html
Imagine a Content Octane Rating that indicates whether content
has the metadata and structural refinement necessary to keep the
business engine running smoothly under load.
• 85: Unleaded; Conventional text file
• 87: Use of basic styling markers (HTML or Markdown)
• 89: Use of semantic phrase markup (var, cite, kbd, code, etc.)
• 90: Use of complex data models (e. g., structures for sections)
• 91: Premium! Supports interaction with rules-driven processing
• What is the Content Octane Rating (COR) of your documents?
• Note also the formalized rating system, DITA Maturity Model
7. About This Presentation
There is value in having structured information.
How to get started? We’ll cover:
1. High level goals of an Information Model
2. Comparative overview of some sample designs
from the DITA community:
• What were they thinking, good or bad?
• How would I organize and structure my own content?
3. Summarize a design approach you can apply
for your content
8. 1. Goals of Information Models
• “An Information Model is a set of principles that define how
you intend to structure the information you develop.”
-- JoAnn Hackos, CIDM Newsletter, Feb. 2010
• It is a contract between the document and the outside world:
• For querying into the document (not just full text search)
• For processing the content in ways that support the business
• For publishing the content as its readers need or prefer
9. A Model Is:
A representation of the
underlying Information
Architecture. It helps:
• Builders (authors, tool
vendors) to create
conforming instances
of the model
• Occupants (readers,
publishing tools) to
navigate and get best
use of those facilities.
Photo credit: Cushing Memorial Library and Archives, Texas
A&M /Foter / Creative Commons Attribution 2.0 Generic (CC BY 2.0)
10. An Information Model Promotes:
• Consistency of writing style
• Readers can anticipate where they want to look
• Separation of formatting concerns from the model itself
• Useful data types for processing:
• Semantic intent for search relevance
• Structure to indicate scope of relevant content
• Association of business rules to the content:
• Management of translation process
• Automation of workflow and QA controls
• Automation of backup, version control
• Ability to share interoperable content with business partners,
OEMs, and customers, as needed
12. 2. Comparative Review
• Available Cases:
• XML Applications and Initiatives (at last count, 594!)
• http://xml.coverpages.org/xmlApplications.html
• DITA Open Toolkit plugins
• Various locations, but manageable number
• We will go with DITA OT-compatible designs
• Methodology (CSI model):
• The Lineup
• Psychological Profile (What were they thinking?)
• Motive (What were they trying to accomplish?)
• Modus Operandi (How did they do it?)
• Applicable Charges (What can we learn from mistakes and wins?)
14. DITA Open Toolkit Plugins
• For this particular lineup (a spectrum of quality):
• Music: https://github.com/dita-ot/ext-plugins/tree/master/music
• MsgRef: http://sourceforge.net/projects/dita-ot/files/Plug-
in_message%20specialization/
• Faq: https://github.com/dita-ot/ext-plugins/tree/master/faq
• eNote: https://github.com/dita-ot/ext-plugins/tree/master/enote
• Known plugin repositories (some duplicates):
• https://github.com/dita-ot/ext-plugins (models, extensions)
• https://github.com/robander/metadita (extension points)
• http://sourceforge.net/projects/dita-ot/files/ (stable releases)
• https://groups.yahoo.com/neo/groups/dita-users/files/Demos/
15. Music plugin
Characteristic Assessment
Line of business Personal demo by Robert Anderson, DITA OT lead
Apparent business driver Reduce Robert’s time spent in teaching plugin
concepts; exemplar for plugin authors (DTDs and
processing hooks); enable greater DITA-OT uptake
Design methodology Model a typical “collector’s database” (portfolio)
Use of typed data Sorting CDs/songs by categories and types; extends
<simpletable> as a relational database.
Usability Obvious, meaningful element names
Utility For CD/song collections, mainly of personal interest;
as a teaching tool, highly useful
Compelling virtues Well documented; complete application with
multiple outputs and even some editor support
Odious flaws None
https://github.com/dita-ot/ext-plugins/tree/master/music
16. Music DTD fragment
• <!-- LONG NAME: Music Collection -->
• <!ELEMENT songCollection (%title;, (%titlealts;)?, (%shortdesc; | %abstract;)?,
• (%prolog;)?, (%songBody;)?, (%related-links;)?,
• (%song-info-types;)* ) >
• <!-- LONG NAME: Music Body -->
• <!ELEMENT songBody ((%section; | %simpletable; | %songList;)* ) >
• <!-- LONG NAME: -->
• <!ELEMENT songList ((%songRow;)+) >
•
<!-- LONG NAME: -->
• <!ELEMENT songRow ((%song;)?, (%album;)?, (%artist;)?,(%genre;)?,
• (%rating;)?,(%count;)?,(%playdate;)?)>
•
<!-- LONG NAME: -->
• <!ELEMENT song (%ph.cnt;)* >
•
<!-- LONG NAME: -->
• <!ELEMENT album (%ph.cnt;)* >
•
<!-- LONG NAME: -->
• <!ELEMENT artist (%ph.cnt;)* >
•
<!-- LONG NAME: -->
• <!ELEMENT genre (%ph.cnt;)* >
•
<!-- LONG NAME: -->
• <!ELEMENT count (%ph.cnt;)* >
•
• <!-- LONG NAME: -->
• <!ELEMENT playdate (%ph.cnt;)* >
18. Msgref plugin
Characteristic Assessment
Line of business Software company (but could be hardware codes)
Apparent business driver Single source for content that appears in both
product interfaces and in documentation (to lower
translation redundancy, for example)
Design methodology Represent the Java Resource Bundle structure
Use of typed data Deliberate, strongly fielded (see the msgID “title”)
Usability Abbreviated element names (probably necessary
due to wordiness of the domain, but an NLS issue);
Difficult to write without a fielded editing tool.
Utility Very good fit for the designed purpose (hands-off
reuse of message strings)
Compelling virtues Natural use of a “message” infotype and fields
Odious flaws Development costs for authors and tools interfaces
http://sourceforge.net/projects/dita-ot/files/Plug-in_message%20specialization/
21. FAQ plugin
Characteristic Assessment
Line of business Support organizations; call centers
Apparent business driver Capture resolved issues as new best practice
responses for subsequent problem calls
Design methodology Assess the structure of conventional FAQs on the
Web, model the design as a DITA specialization
Use of typed data Rich information type (top-down) and categories;
some internal semantic terms as well
Usability Is functional, obvious; could be extended as needed
Utility The authoring problem it addresses is already
solved by knowledge base applications; better
suited as a “delivery aggregator”
Compelling virtues Simple, clear information model
Odious flaws None; could actually be used for “DITA on the Web”
https://github.com/dita-ot/ext-plugins/tree/master/faq
24. Enote plugin
Characteristic Assessment
Line of business Mimics existing email tools; demonstrates using
content structures for header metadata
Apparent business driver Demo only; not in response to a business need
Design methodology Demonstrate “XML data islands” within standard
note structures.
Use of typed data Yes, for the header data islands
Usability Good to see how content can be used for data; to
some extent, this need is handled by DITA 1.2 +
Utility Not a real application
Compelling virtues Good teaching tool (like a car engine cut in half)
Odious flaws No longer a best practice for embedded data; use
the new <data> element
https://github.com/dita-ot/ext-plugins/tree/master/enote
27. 3. A Design Approach for DITA
1. Determine the business imperative
2. Identify stakeholders
3. Get sponsorship and team
4. Analysis & design:
• Top-down: Identify information types and content structures
• Bottom-up: Identify keywords and data types
• Find a good-enough depth of concerns (Best is enemy of good)
• Test usability of names (elements, attributes, value keywords)
• Test usability of design in an actual XML editor
• Test publishing/processing/search effectiveness
• Document early; capture lessons often
5. Report up
6. “Make it so, Number One!”
28. On your own:
Smaller project ideas
• Recipes
• Meeting minutes
• Database for collections (action figures, cameras, stamps, etc.)
• APIs
• Unix-style “man pages”
• Trading cards, baseball or Pokémon style
• Neighborhood newsletter/web site
• “Kleine Kinder, kleine Sorgen, große Kinder, große Sorgen.“
29. On your own:
New or reused?
• Port an existing design to your framework (for example, apply
this design to a DITA framework: http://www.happy-
monkey.net/recipes/)
• Represent an existing process in the model (basically what the
enote demo did)
• Port existing to your framework, then augment with your
process requirements
30. On your own:
Considerations
• Ease of authoring
• Clear distinction of “things” vs “properties”
• Naming: clarity vs verbosity
• Balance between precision and usability:
• Avoid needing to parse key data in your processor
e. g. <date>June 12 2014</date> for Europeans
• On the other hand, avoid too much detail:
<sentence>
<word>This</word> <word>is</word> <word>just</word>
<word>wrong!</word>
</sentence>
31. Here be Dragons!
• How will your chunks be used? Each new process represents a
new “application context” for the collection.
• What business rules need to be supported by the process? Are
they part of the application-level information model?
• Roll your own or involve a consultant?
• What are the costs of support and maintenance?
• What are the costs of training and getting up to speed?
32. Wrapping up
• Skills you may want to learn:
• UML or “Data Modeling 101”
• XML schema design
• Editor configuration (EDDs for FrameMaker)
• Web forms for simple fielded interfaces
• Where to find outside help
• https://groups.yahoo.com/neo/groups/dita-users/info
• LinkedIn XML- and DITA-related groups
• Support lists for the authoring and CMS tools you have