The Dynamic Information Model

The Dynamic Information Model
Supporting the Information Model with auto-generated
Schematron patterns, tool tips, and constraints
George BinaDawn Stevens

Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Why do I need one?
● DITA provides core information types, but no
instructions for when to use them
● DITA has hundreds of elements; most
companies use less than half of them
● DITA has a relatively flexible structure; most
companies tighten it up

What is an information model?
• A set of specifications that defines
• The structure of your information
• The architectural elements to be used
• The expected outputs
• The required functionality of your authoring
environment

What does it contain?
● Information types
● Block and inline elements
● Metadata taxonomy
● Mapping guidelines
● Linking strategies
● Reuse mechanisms
● Authoring guidelines

How is it enforced?
● Code reviews
● Templates and tool tips
● Subject scheme maps
● Automated tools and Schematron
● Constraints and specializations

Who enforces it?
Information architect creates / maintain the
information model
BUT, will not usually have these skills:
● Schematron
● XML schema languages (DTD, XML Schema, Relax
NG)
● Complex tool configuration

Wouldn't it be nice if...
● The work you did to create the information
model could be single-sourced into automated
enforcement?
● You didn't need specialized skills to create
those tools?

Business needs meet technology
Style
guide make it accessible to
enforce rules
Dynamic
Information
Model
Technologies
killer applications
used by anyone

Overview
Ideas behind DIM
The DIM project
Demo
Future plans
Q&A

A little bit of recent history...
Related presentations at previous conferences
– DITA North America 2013
How to make a style guide available to authors
– DITA North America 2014
Schematron use cases for DITA
– DITA Europe 2014
Introducing the DIM project

DITA North America 2013
Make the style guide available to authors
– We should not expect authors to learn the style guide
and then start writing
– The style guide information should be made available to
them as they need it
– We developed a configuration file for oXygen to allow
linking from the documentation tooltips to the style guide
topics relevant to the current editing context
Style
guide

DITA North America 2014
Using Schematron for DITA
If we create a library of generic rules then we can use
them without Schematron knowledge, just by providing
values for the rule parameters
<pattern is-a="recommendElementInParent">
<param name="parent" value="task"/>
<param name="element" value="shortdesc"/>
<param name="message"
value="Do not forget to add a short description to your task!"/>
</pattern>
These rules can be used to enforce business specific
constraints documented in a style guide
parent
element
message
Generic rule

DIM Ideas
Style
guide
+ +
Smart
style guide
generate

DIM Ideas
● Generate the style guide integration
configuration file from the style guide itself
● Encode business rules within the style guide,
next to the text that describes them
● Make authoring of style guide metadata and
rules very easy to use

DITA Europe 2014
Introducing the DIM project
– Single source style guide as
● descriptive prose
● code to automatically enforce those rules
– Support information architects in defining rules encoded
within the style guide though a simple user interface
– Make the style guide more accessible by annotating
topics with metadata information
– Automatically generate Schematron rules and
configuration files from the style guide information

DIM
Take advantage of structured information to
define an intelligent style guide
– Encode business rules within the style guide
– Encode metadata information
Provide a user friendly authoring interface for
rules and metadata

Encode business rules
<pattern is-a="restrictWords"
see="http://example.com/styleguide/webhelp/c_WritingShortDescriptions.html">
<param name="parentElement" value="shortdesc"/>
<param name="minWords" value="1"/>
<param name="maxWords" value="50"/>
</pattern>
<section audience="rules">
...
<dl><dlhead>
<dthd>Rule</dthd><ddhd>restrictWords</ddhd>
</dlhead><dlentry>
<dt>parentElement</dt><dd>shortdesc</dd>
</dlentry><dlentry>
<dt>minWords</dt><dd>1</dd>
</dlentry><dlentry>
<dt>maxWords</dt><dd>50</dd>
</dlentry></dl>
...
</section>
Schematron
DITA

Metadata
<mapping elementName="shortdesc"
path="c_WritingShortDescriptions.html"
type="link"
linkText="How to write short descriptions"/>
<data
name="shortdesc"
value="How to write short descriptions"
audience="styleguide"/>
Configuration file
DITA

The DIM project
Open source (Apache 2.0 license)
Available on GitHub
http://www.github.com/oxygenxml/dim

DIM project content
● A generic DITA style guide provided by
Comtech Services that can be used as a
starting point for your own style guide
● A Schematron library of generic rules that can
be instantiated to implement actual rules
● oXygen customization to provide an easy
authoring environment for rules and metadata
● XSLT scripts to generate Schematron rules and
an oXygen configuration file
● Other resources (XML Catalog, configuration)

DIM project deliverables
● Style guide output as WebHelp and other
formats
● A Schematron schema containing all the rules
defined within the style guide
● An oXygen configuration file to enable links
from element or attribute tooltips to the style
guide topic.

DIM Demo
● Project layout
● Available abstract patterns library
● Defining a new rule
● Generate the Schematron rules file
● Using the Schematron rules
● Quick Fixes in action
● Link an element to a style guide topic
● Use the linking information while editing

Project layout

Available abstract patterns library

Available abstract patterns library
<pattern abstract="true" id="avoidEndFragment">
<title>Issue a warning if a an element end with a specified fragment
or character</title>
<p>This pattern allows you to advise users not to use a specific end
sequence to end an element.</p>
<p>As parameters we have <emph>fragment</emph> that points to the
text that we need to check, <emph>element</emph> that points to
the element we will check to not end with that fragment and
<emph>message</emph> that contains the message we should display
to the user in case the fragment appears at the end of the the
specified element.</p>
<parameters xmlns="http://oxygenxml.com/ns/schematron/params">
<parameter>
<name>element</name>
<desc>Specifies the element we will verify to not contain a specified word.</desc>
</parameter>
<parameter>
<name>fragment</name>
<desc>Specifies the text to check.</desc>
</parameter>
<parameter>
<name>message</name>
<desc>The message the end user will see when the specified text ends with the given
fragment.</desc>
</parameter>
</parameters>
<rule context="$element">
<assert test="not(ends-with(normalize-space(.), '$fragment'))"
role="warn" sqf:fix="avoidEndFragment_deleteFragment avoidEndFragment_replaceFragment">
$message
</assert>
</rule>
</pattern>

Defining a new rule

Generate the Schematron rules file

<pattern is-a="avoidEndFragment"
see="http://example.com/styleguide/webhelp/c_CreatingLists.html">
<param name="element" value="li"/>
<param name="fragment" value=";"/>
<param name="message"
value="List items should not end with a semi-column!
If it is a short statement leave it
without any ending character, otherwise use a full stop."/>
</pattern>

Using the Schematron rules

Quick Fixes in action

Link an element to a style guide
topic

Use the linking information while
editing

Future plans
● Define and automatically generate DITA
specializations / constraints
● Generate new document templates and inline
instructions for authors
● √ Build a library of generic rules
● √ Provide Quick Fixes as part of the generic
rules

Thank you!
Questions?
Dawn Stevens
dawn.stevens@comtech-serv.com
@comtechdawn
George Bina
george@oxygenxml.com
@georgebina

The Dynamic Information Model

More Related Content

What's hot

Similar to The Dynamic Information Model

Recently uploaded

The Dynamic Information Model