By George Bina, oxygen Using XML and metadata, an intelligent style guide allows you to automatically enforce the style guide's rules and make the style guide easily discoverable by writers as they work. By automating the compliance checking, you can improve the quality and consistency of your content across the enterprise. In this interactive workshop, we will use DITA to create a sample intelligent style guide. An example is also available as an open source project on GitHub. In this workshop, you will learn: --Why you need an intelligent style guide. --What are the main characteristics of an intelligent style guide. --How to encode an intelligent style guide in DITA. --How users can discover the style guide as they write. --How style guide rules can be enforced or checked automatically. --What you need to get started with your own style guide. --How to create the first version of your own intelligent style guide.

1. | Create an Intelligent Style Guide Using DITA | 1
Create an Intelligent Style Guide Using DITA
Goal
Create an intelligent style guide
• DITA based + publish it on the web
• easily discoverable
• enforceable - how can we make the style guide detect when the user made an error
• feedback from the writers
• what else?
Agenda
Why you need a style guide and its requirements
• Do you have a style guide?
• Why do we need a style guide?
• What format we should choose for our style guide? Here there are some requirements:
• Available in different formats
• Allow linking to a specific section
• Allow metadata/annotations
• Allow automatic processing
DITA-based style guide responds to requirements
• Publish to:
• HTML (WebHelp) - online access
• PDF - print
• EPUB - tablet
• We can link to a specific topics
• Allows metadata in prolog. Metadata information can also be included at any point, for example using profiling
information to mark that as metadata.
• XML based, so we can use XSLT, XQuery, etc. for automatic processing
Let's create a DITA-based style guide!
• Clone the https://github.com/oxygenxml/dim.git repository or download the project from https://github.com/
oxygenxml/dim/archive/lavacon.zip
• Write one or more rules
Example: keep short descriptions between some word and/or character limits
Example: how we should write lists, what can end a list item, can we embed a list into another list, etc.
• Publish the style guide as web help, PDF, EPUB, etc.
Discoverable
• How a writer can we discover the relevant style guide topics as she or he writes a topic?

2. | Create an Intelligent Style Guide Using DITA | 2
• We can link that topic from the authoring tool user interface, on the element or attribute the user is entering, for
example in the annotation hint that describes that element or attribute.
• Other ways of making the style guide available? Maybe we can also generate an inline hint in the document and
include the link to the style guide topic in the hint for an element.
Discuss about the oXygen configuration file that allows presenting links in the documentation of an element or
attribute - we can then think of a way we automate this configuration file, using the style guide as the source of that
information.
We can annotate the topics with the element we want to link from and the link text, then process the style guide to
generate the configuration file.
Show and describe the processing that generates the configuration file.
Annotate the topic, generate the configuration file and test that it works, show the link to the style guide on the
element we annotated the topic with.
We can automate the annotation with a custom action that adds the corresponding markup - the user just needs to fill
in the element and the link text.
Explain the use of the XML Catalog to map the link we put in the configuration file to the actual location of the style
guide.
Enforce style guide rules automatically
Come back to the style guide topic - can we do better than showing a link to the user on an element? Can we
automatically detect when there is a problem noted in the style guide and point the user to that style guide topic?
Schematron allows us to enforce rules and we can use that in oXygen, including Schematron Quick Fixes.
Schematron can be used also to check all topics from a map from the Check DITA Validation and Completeness
action.
Example: See the SQF samples from the oXygen sample project to get an idea of what is possible.
But, we have a problem - the owner of the style guide (information architect) may not know Schematron!
Solution - generic rules implemented as Schematron abstract patterns - separate concerns and we can identify two
roles
• developer
• information architect
Workflow: the information architect will try to create a new rule selecting from the available generic rules and
setting the values of the parameters. If no rule is available for what he wants, he will ask the developers to build a
new generic rule and he will provide the description for the new rule and what parameters are needed. Once the new
generic pattern is available, the information architect can create the new rule.
Single source the rules in the style guide
We have a simpler way of building rules, but this still requires Schematron knowledge and also the style guide and the
rules are separate. We have DITA as the style guide source, so we should annotate the topics with the rule information
and generate the Schematron out of that.
Describe the markup for embedding rules into DITA topics (section/@audience="rules", definition list for each rule,
term as parameter name, description as parameter value.
UI for easy entering new rules - just select the generic rule and set values for parameters.
Automatic extraction of rules as Schematron + bonus, link from the rule to the style guide topic the rule was defined
in.
Use the available rules to enforce different constraints
Let's build together the style guide and add enforce it by instantiating the generic rules.

3. | Create an Intelligent Style Guide Using DITA | 3
If we have time, we may also build a new generic rule - I will play the role of the developer - you play the role of the
information architect.
Feedback from writers
Two possibilities - publish to an output format that includes feedback - we provide a feedback enabled WebHelp
format.