One of an Information Architect’s main roles is to develop and maintain an organization’s Information Model. But it’s usually up to other roles—tools and editorial, specifically—to express and enforce the Model. Wouldn’t it be nice if during the act of writing the Information Model, the IA was simultaneously creating the automatic enforcement and expression of the Model in the authoring environment?
In this presentation, George and Dawn show how an IA can author an organization’s Information Model using DITA topics and maps—as is the industry standard practice—but take it one step further, with the IA’s input being used as the specifications for auto-generated Schematron rules and tool tips.
Unblocking The Main Thread Solving ANRs and Frozen Frames
The Dynamic Information Model
1. The Dynamic Information Model
Supporting the Information Model with auto-generated
Schematron patterns, tool tips, and constraints
George BinaDawn Stevens
2. 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
3. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
4. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
What does it contain?
● Information types
● Block and inline elements
● Metadata taxonomy
● Mapping guidelines
● Linking strategies
● Reuse mechanisms
● Authoring guidelines
5. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
How is it enforced?
● Code reviews
● Templates and tool tips
● Subject scheme maps
● Automated tools and Schematron
● Constraints and specializations
6. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
7. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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?
8. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Business needs meet technology
Style
guide make it accessible to
enforce rules
Dynamic
Information
Model
Technologies
killer applications
used by anyone
9. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Overview
Ideas behind DIM
The DIM project
Demo
Future plans
Q&A
10. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
11. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
12. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
13. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
DIM Ideas
Style
guide
+ +
Smart
style guide
generate
14. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
15. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
16. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
17. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
18. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
19. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
The DIM project
Open source (Apache 2.0 license)
Available on GitHub
http://www.github.com/oxygenxml/dim
20. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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)
21. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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.
22. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
23. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Project layout
24. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Project layout
25. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Available abstract patterns library
26. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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>
27. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Defining a new rule
28. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Defining a new rule
29. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Generate the Schematron rules file
<!--Generated from c_CreatingLists.dita.
-->
<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>
30. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Using the Schematron rules
31. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Using the Schematron rules
32. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Quick Fixes in action
33. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Quick Fixes in action
34. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Link an element to a style guide
topic
35. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Link an element to a style guide
topic
36. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Link an element to a style guide
topic
37. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Use the linking information while
editing
38. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
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
39. Copyright @ Syncro Soft, 2015. All rights reserved.Copyright @ Syncro Soft, 2015. All rights reserved.
The Dynamic Information ModelThe Dynamic Information Model
Thank you!
Questions?
Dawn Stevens
dawn.stevens@comtech-serv.com
@comtechdawn
George Bina
george@oxygenxml.com
@georgebina