the dynamic information model

The Dynamic Information ModelSupporting 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 authoringenvironment



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 theinformation 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 automatedenforcement?

● You didn't need specialized skills to createthose tools?



Business needs meet technology

Styleguide make it accessible to

enforce rules

DynamicInformation

Model

Technologies

killer applicationsused 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 guidetopics relevant to the current editing context

Styleguide



DITA North America 2014

Using Schematron for DITAIf we create a library of generic rules then we can usethem without Schematron knowledge, just by providingvalues 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 specificconstraints documented in a style guide

parentelement

message

Generic rule



DIM Ideas

Styleguide + +

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 encodedwithin the style guide though a simple user interface

– Make the style guide more accessible by annotatingtopics with metadata information

– Automatically generate Schematron rules andconfiguration files from the style guide information



DIM

Take advantage of structured information todefine an intelligent style guide

– Encode business rules within the style guide– Encode metadata information

Provide a user friendly authoring interface forrules 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

http://www.github.com/oxygenxml/dim



DIM project content● A generic DITA style guide provided by

Comtech Services that can be used as astarting point for your own style guide

● A Schematron library of generic rules that canbe instantiated to implement actual rules

● oXygen customization to provide an easyauthoring environment for rules and metadata

● XSLT scripts to generate Schematron rules andan 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 styleguide 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 givenfragment.</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 guidetopic



Use the linking information whileediting



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 [email protected]

@comtechdawn

George [email protected]

@georgebina

mailto:[email protected]

mailto:[email protected]

the dynamic information model

Technology

syncro soft

information architect

information types block

core information types

schematron constraints

schematron use cases

authors dita north america

architectural elements