Thursday, March 03, 2016

Implementing your own Style Guide

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Let's say you are a team of tech writers collaborating on a DITA-based project and doing things your way, maybe you have various best practices about what elements to use and when to use them, maybe you want to impose a set of controlled values for certain attributes. So at some point you gather on an internal server a set of HTML resources which explain how various DITA elements should be used. This blog post will attempt to show you how these best practices can be shared with your team so that they are readily available when editing DITA content in Oxygen.

Custom "Style Guide" toolbar button

As you have your style guide HTML resources on a server, you can add a custom toolbar button which will appear on the DITA toolbar when editing DITA topics in the Author editing mode. When you press that toolbar button, a web browser opens up and shows you the style guide main page. Here are some steps about how to do this:

  1. In the Oxygen Preferences->Document Type Association page edit the DITA framework. Instead of editing the DITA framework directly you may choose to extend it in order to share the extension more easily:http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html.
  2. In the Author tab go to the Actions tab and there is an action with the ID styleguide. If you edit the action, it invokes an operation with a parameter called resourcePath. You can edit that parameter to point to your internal (or public) server where the WebHelp output is stored. You should also set an icon to it, you can use /images/BrowseReferenceManual16.png (it's a default icon which comes with Oxygen). Save your changes in that dialog.
  3. In the Author tab there is a Toolbar sub-tab in which you can add the styleguide action to the toolbar in the place where you want it. Press OK a couple of times in the dialogs and then action should become available on the toolbar for each topic.

Link to Style Guide for each element in the content completion window

When you press the ENTER key in the Author editing mode, you get a list of available elements. For each element there is documentation available, that documentation can be customized, for example you could add links for each element to a specific section in your style guide. This topic should tell you more about how this can be achieved:https://www.oxygenxml.com/doc/versions/17.1/ug-editor/#tasks/author-styleguide-annotations.html

Impose controlled attribute values

For certain attributes (for example profiling attributes, @outputclass attributes) you may want to impose a set of controlled attribute values. This blog post will tell you how: http://blog.oxygenxml.com/2015/07/controlled-attribute-values-for-your.html.

Show validation errors or warning when guidelines are breached

If possible, some of your rules can be converted to Schematron, allowing the application to signal to the writer when a rule is not obeyed. You can also add quick fixes to show writers various ways to rectify the problem. This blog post should give you more details about this:http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.

Bringing all of this together

There is an Oxygen XML GitHub project called DIM which attempts to approach most of these aspects in an unified manner: https://github.com/oxygenxml/dim.

Wednesday, March 02, 2016

Resources for learning DITA with Oxygen

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

From time to time we get requests from beginners or from users migrating from other tools who want to start using Oxygen with DITA and they need to know a set of useful resources.

Resources for editing DITA with Oxygen:

We have a getting started section in our user's manual: https://www.oxygenxml.com/doc/versions/17.1/ug-editor/#topics/eppo-first-dita-topic.html and a larger section on DITA authoring: https://www.oxygenxml.com/doc/versions/17.1/ug-editor/#topics/author-dita.html.

There are two past webinars about DITA support in Oxygen, you can follow them on our Oxygen YouTube channel: https://www.youtube.com/watch?v=j7LMcO_euJU.

And we have a list of videos, some of them DITA-related here: https://www.oxygenxml.com/videos.html.

Resources for learning DITA:

If you want to start learning about DITA in general there is a web site called Learning DITA.

The DITA 1.3 standard specification can be found here: https://www.oxygenxml.com/dita/1.3/specs/#introduction/dita-release-overview.html.

There are also a number of good books like DITA For Practitioners and the DITA Style Guider.

Resources for customizing the DITA output formats

Usually customizing the XHTML based outputs means creating your custom CSS selectors. If you generate WebHelp output using Oxygen, we have a section explaining basic WebHelp customizations: https://www.oxygenxml.com/doc/versions/17.1/ug-editor/#topics/customize_webhelp.html.

For PDF-based outputs if you publish via the DITA Open Toolkit we have a section in our user's manual about PDF customizations: https://www.oxygenxml.com/doc/versions/17.1/ug-editor/#topics/dita-pdf-output.html. There is also a PDF plugin generator created by Jarno Elovirta which can be used in order to customize the PDF layout. The DITA For Print book also covers quite a lot of many customization possibilities. There are also a number of different alternatives to obtain PDF from DITA: http://blog.oxygenxml.com/2015/11/possibilities-to-obtain-pdf-from-dita.html.

DITA Trivia

There are a number of blogs on which you can read various DITA-related articles:

Community

The DITA Users List is probably the first place where you can register and ask for help with DITA-related issues. There is also a Google Groups DITA Users List. Most DITA Users register sooner or later on one of these groups.
There is also a DITA Awareness Group on Linked In.