Oxygen Tips and Tricks for Happy Writers and

Abstract For DITA beginners, especially those moving from unstructured authoring, there’s a lot to

Agenda 1. 2. 3. 4. 5. 6. 7. Questions, comments, suggestions, and ideas welcome

Agenda 1. 2. 3. 4. 5. 6. 7. Background Ask the Audience The Magic

Background • Technical Writer @ AIR Worldwide • Leading conversion from Word/Robo. Help to

Background: Our Project • Doc set: – 160+ (and growing!) Word docs – Average

Background: Our Team • Approx. 10 writers • Varying levels of experience with –

Ask the Audience 1. What is your level of DITA expertise? – Total newbie

Ask the Audience 2. At what stage is your DITA project/environment? – Contemplating DITA

Ask the Audience 3. Which version of DITA are you using? – 1. 3

Ask the Audience 4. Are you currently using Oxygen customizations? – Yes – No

The Oxygen DITA Extension Duplicate the Oxygen DITA framework to create an extension to

Custom Refactoring – What is it? • Change generic topics to custom concept/task/ reference.

Custom Refactoring – What is it? • Change topic ID to use custom, consistent

Custom Refactoring – How to? 1. Use the DITA framework refactoring files as a

Custom Refactoring – How to? 3. Edit/customize. Example: Refactor to custom concept topic ©

Custom Refactoring – How to? 4. Add the custom refactoring files to the Oxygen

Custom Author Actions – What is it? • Our team is using @rev to

Custom Author Actions – What is it? Two use cases: 1. Entire element has

Custom Author Actions – What is it? • Tagging each change manually with @rev

Custom Author Actions – What is it? Sooo… Let’s make it easier and faster.

Custom Author Actions – How to? 1. Add two custom Oxygen author actions to

Custom Author Actions – How to? © 2018 AIR Worldwide 33 33

Custom Author Actions – How to? 2. Each writer configures a custom editor variable

Custom Author Actions – Results? • Pressing Ctrl-R tags the element that currently contains

Schematron Quick Fixes – What are they? • Our team uses a collection of

Schematron Quick Fixes – What are they? Again, we want to make this process

Schematron Quick Fixes – What are they? Schematron is “a language for making assertions

Schematron Quick Fixes – What are they? © 2018 AIR Worldwide 40 40

Schematron Quick Fixes – How to? 1. Add a rules file to the Oxygen

Schematron Quick Fixes – How to? Note: • Rule order matters. (Check for larger

Schematron Quick Fixes – How to? 2. Configure the Oxygen DITA extension to recognize

Schematron Quick Fixes – How to? 3. You or each writer can enable automatic

Ask the Audience, Part 2 Please share your Oxygen tips and tricks! © 2018

Slides: 49

Download presentation

Abstract For DITA beginners, especially those moving from unstructured authoring, there’s a lot to learn and remember: Using keys consistently instead of literal strings, remembering to assign useful topic IDs, and lots more. As a DITA infrastructure engineer for a team of DITA newbies, there are some easy things that you can do in Oxygen go to make these tasks easier and more obvious for your team. In addition to happier writers, the benefits for you include a more consistent DITA topic set, right from the start. © 2018 AIR Worldwide 2 2

Agenda 1. 2. 3. 4. 5. 6. 7. Questions, comments, suggestions, and ideas welcome at any time! Background Ask the Audience The Magic of the Oxygen DITA Extension Custom Refactoring Custom Author Actions Schematron Quick Fixes Ask the Audience, Part 2: More Tips and Tricks? © 2018 AIR Worldwide 3 3

Agenda 1. 2. 3. 4. 5. 6. 7. Background Ask the Audience The Magic of the Oxygen DITA Extension Custom Refactoring Custom Author Actions Schematron Quick Fixes Ask the Audience, Part 2: More Tips and Tricks? © 2018 AIR Worldwide 4 4

Background • Technical Writer @ AIR Worldwide • Leading conversion from Word/Robo. Help to DITA • Proud graduate of the Stan Doherty School of DITA • Experience trial-and-error-ing my way through our DITA specializations, DITA-OT customizations, and information architecture • Proponent of sharing, adopting, and adapting DITArelated ideas © 2018 AIR Worldwide 5 5

Background: Our Project • Doc set: – 160+ (and growing!) Word docs – Average page count per doc = 100+ – Robo. Help project w/ 1000+ topics • Environment: – TFS source control – TFS CI builds © 2018 AIR Worldwide 7 7

Background: Our Team • Approx. 10 writers • Varying levels of experience with – DITA – Structured authoring – Source control • Varying writing backgrounds – Academic – Software • Varying learning styles © 2018 AIR Worldwide 9 9

Ask the Audience 2. At what stage is your DITA project/environment? – Contemplating DITA – Planning / Just beginning – Converting to DITA – Fully converted and actively authoring, publishing, etc. – Pushing the boundaries to new and exciting things © 2018 AIR Worldwide 13 13

The Oxygen DITA Extension Duplicate the Oxygen DITA framework to create an extension to contain the Oxygen customizations for your team. Each writer specifies the location of the extension. Store in source control (perhaps in your DITA-OT) so that your team can always access the latest version. © 2018 AIR Worldwide 17 17

Custom Refactoring – How to? 1. Use the DITA framework refactoring files as a base. 2. Copy these files to the framework extension file set. 3. Edit/customize. 4. Add the custom refactoring files to the Oxygen DITA extension. © 2018 AIR Worldwide 21 21

Custom Author Actions – What is it? • Our team is using @rev to mark the changes for each release. • We have a set of controlled attribute values. • Each writer tends to work on a single document/release for a period of time. • Tagging each change manually with @rev is normally a multi-mouse-click process. © 2018 AIR Worldwide 27 27

Custom Author Actions – What is it? • Tagging each change manually with @rev is normally a multi -mouse-click process. • An arduous, annoying, repetitive process leads to: – Resistance to using @rev to track changes – Inconsistent application of this tagging standard – Unhappy writers who blame DITA for this annoyance (which certainly doesn’t help our goal of successful DITA adoption) © 2018 AIR Worldwide 29 29

Custom Author Actions – What is it? Sooo… Let’s make it easier and faster. Use a pair of custom Oxygen author actions linked to keyboard shortcuts to tag changes with @rev attributes. Ø We reduce the @rev tagging effort to a quick keyboard combo. © 2018 AIR Worldwide 30 30

Custom Author Actions – How to? 1. Add two custom Oxygen author actions to the DITA extension. – Assign a keyboard shortcut to each. 2. Each writer configures a custom editor variable to indicate the currently desired (controlled) @rev attribute value. © 2018 AIR Worldwide 31 31

Custom Author Actions – Results? • Pressing Ctrl-R tags the element that currently contains the cursor with @rev=“[whatever the writer assigned to the custom editor variable]” • Selecting text and pressing Ctrl-E wraps the highlighted text in a phrase element and tags this ph with @rev=“[whatever the writer assigned to the custom editor variable]” © 2018 AIR Worldwide 35 35

Schematron Quick Fixes – What are they? • Our team uses a collection of common keys defined in a series of “resources” maps. – Company names – Product names – Terminology – Links to AIR websites • When converting content from Word to DITA or when creating new content, writers must convert literal strings to the corresponding <keyword keyref=“[appropriate key]”/> © 2018 AIR Worldwide 37 37

Schematron Quick Fixes – What are they? Again, we want to make this process as quick and painless as possible… • To encourage consistent use of keys. • To help our writers be happy and like DITA. © 2018 AIR Worldwide 38 38

Schematron Quick Fixes – What are they? Schematron is “a language for making assertions about the presence or absence of patterns in XML documents. ” (http: //schematron. com/) “Schematron Quick Fixes are an extension of the Schematron language and they allow you to define fixes for Schematron validation messages. ” (https: //www. oxygenxml. com/doc/versions/20. 1/ug-editor/topics/schematronquick-fixes-x-editing 2. html) © 2018 AIR Worldwide 39 39

Schematron Quick Fixes – How to? 1. Add a rules file to the Oxygen DITA extension file set and configure the rules file to include all your Quick Fixes. For example: air-rules. sch 2. Configure the Oxygen DITA extension to recognize the rules file. 3. You or each writer can enable automatic validation using this rules file. Oxygen Webinar: https: //www. oxygenxml. com/events/2018/webinar_creating_schematron_rules_and_quick_fixes. html © 2018 AIR Worldwide 41 41

Schematron Quick Fixes – How to? 1. Add a rules file to the Oxygen DITA extension file set and configure the rules file to include all your Quick Fixes. For example: air-rules. sch © 2018 AIR Worldwide 42 42