| Create an Intelligent Style Guide Using DITA | 1

Create an Intelligent Style Guide Using DITA

GoalCreate 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?

| 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, forexample 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 andinclude 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 orattribute - we can then think of a way we automate this configuration file, using the style guide as the source of thatinformation.

We can annotate the topics with the element we want to link from and the link text, then process the style guide togenerate 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 theelement we annotated the topic with.

We can automate the annotation with a custom action that adds the corresponding markup - the user just needs to fillin 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 styleguide.

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 weautomatically 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 Completenessaction.

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 tworoles

• developer• information architect

Workflow: the information architect will try to create a new rule selecting from the available generic rules andsetting the values of the parameters. If no rule is available for what he wants, he will ask the developers to build anew generic rule and he will provide the description for the new rule and what parameters are needed. Once the newgeneric 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 therules are separate. We have DITA as the style guide source, so we should annotate the topics with the rule informationand 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 definedin.

Use the available rules to enforce different constraints

Let's build together the style guide and add enforce it by instantiating the generic rules.

| 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 theinformation architect.

Feedback from writers

Two possibilities - publish to an output format that includes feedback - we provide a feedback enabled WebHelpformat.