Oxygen Tips and Tricks for Happy Writers and More Consistent Docs - PowerPoint Presentation

343 views
Uploaded On 2020-08-06

Oxygen Tips and Tricks for Happy Writers and More Consistent Docs - PPT Presentation

Debbie Femia AIR Worldwide For DITA beginners especially those moving from unstructured authoring theres a lot to learn and remember Using keys consistently instead of literal strings remembering to assign useful topic IDs and lots more ID: 800595

custom dita quick oxygen dita custom oxygen quick fixes schematron audience author actions refactoring extension background rules file tips

Link:

Copy

Embed:

<iframe width="560" height="315" src="https://www.docslides.com/embed/800595" frameborder="0" allowfullscreen></iframe>

Download Presentation from below link

Download The PPT/PDF document "Oxygen Tips and Tricks for Happy Writers..." is the property of its rightful owner. Permission is granted to download and print the materials on this web site for personal, non-commercial use only, and to display it on your personal computer provided you do not modify the materials and that you retain all copyright notices contained in the materials. By downloading content from our website, you accept the terms of this agreement.

Presentation Transcript

Slide1

Oxygen Tips and Tricksfor Happy Writers and More Consistent Docs

Debbie Femia

AIR Worldwide

Slide2

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.

Abstract

Slide3

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom RefactoringCustom Author ActionsSchematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Questions, comments, suggestions, and ideas welcome at any time!

Slide4

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom Refactoring

Custom Author Actions

Schematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Slide5

Technical Writer @ AIR Worldwide

Leading conversion from Word/RoboHelp to DITA

Proud graduate of the Stan Doherty School of DITAExperience trial-and-error-ing my way through our DITA specializations, DITA-OT customizations, and information architectureProponent of sharing, adopting, and adapting DITA-related ideas

Background

Slide6

Doc set:

160+ (and growing!) Word docs

Average page count per doc = 100+RoboHelp project w/ 1000+ topics

Background: Our Project

Slide7

Doc set:

160+ (and growing!) Word docs

Average page count per doc = 100+RoboHelp project w/ 1000+ topicsEnvironment:TFS source controlTFS CI builds

Background: Our Project

Slide8

Doc set:

160+ (and growing!) Word docs

Average page count per doc = 100+RoboHelp project w/ 1000+ topicsEnvironment:TFS source controlTFS CI builds

Background: Our Project

DITA on a shoestring

(high-quality)

Slide9

Approx. 10 writers

Varying levels of experience with

DITAStructured authoringSource controlVarying writing backgroundsAcademic

Software

Varying learning styles

Background: Our Team

Slide10

Approx. 10 writers

Varying levels of experience with

DITAStructured authoringSource controlVarying writing backgroundsAcademic

Software

Varying learning styles

Background: Our Team

https://www.infomanagementcenter.com/product/webinar-dita-worst-practices/

Slide11

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom Refactoring

Custom Author Actions

Schematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Slide12

What is your level of

DITA expertise?

Total newbie

Author

Advanced

DITA wizard

Ask the Audience

Slide13

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

Ask the Audience

Slide14

Which version of DITA

are you using?

1.3

1.2

Earlier version

Ask the Audience

Slide15

Are you currently using

Oxygen customizations?

Yes

Ask the Audience

Slide16

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom Refactoring

Custom Author Actions

Schematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Slide17

Duplicate the Oxygen DITA framework to create an

extension to contain the Oxygen customizations for your team.

Store in source control (perhaps in your DITA-OT)

so that your team can always access the latest version.

The Oxygen DITA Extension

Each writer specifies the location of the extension.

Slide18

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom Refactoring

Custom Author Actions

Schematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Slide19

Change generic topics to custom concept/task/ reference.

Custom Refactoring – What is it?

Slide20

Change topic ID to use custom, consistent pattern.

Custom Refactoring – What is it?

id=“concept_now-concept-topic”

Slide21

Use the DITA framework refactoring files as a base.

Copy these files to the framework extension file set.

Edit/customize.Add the custom refactoring files to the Oxygen DITA extension.

Custom Refactoring – How to?

Slide22

Use the DITA framework refactoring files as a base.

Copy these files to the framework extension file set.

Custom Refactoring – How to?

Slide23

Edit/customize.

Example: Refactor to custom concept topic

Custom Refactoring – How to?

Slide24

Edit/customize.

Example: Refactor to custom concept topic

Custom Refactoring – How to?

Slide25

Add the custom refactoring files to the Oxygen DITA extension.

Custom Refactoring – How to?

Slide26

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom Refactoring

Custom Author Actions

Schematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Slide27

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.

Custom Author Actions – What is it?

Slide28

Two use cases:

Entire element

has changed.

Just a phrase

has changed.

Custom Author Actions – What is it?

Slide29

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 changesInconsistent application of this tagging standardUnhappy writers who blame DITA

for this annoyance

(which certainly doesn’t help our

goal of successful DITA adoption)

Custom Author Actions – What is it?

Slide30

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.

Custom Author Actions – What is it?

Slide31

Add two custom Oxygen author actions to the DITA extension.

Assign a keyboard shortcut to each.

Each writer configures a custom editor variable to indicate the currently desired (controlled) @rev attribute value.

Custom Author Actions – How to?

Slide32

Add two custom Oxygen author actions to the DITA extension.

Custom Author Actions – How to?

Slide33

Custom Author Actions – How to?

Slide34

Each writer configures a custom editor variable to indicate the currently desired (controlled) @rev attribute value.

Custom Author Actions – How to?

Slide35

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]”

Custom Author Actions – Results?

Slide36

Background

Ask the Audience

The Magic of the Oxygen DITA ExtensionCustom Refactoring

Custom Author Actions

Schematron Quick Fixes

Ask the Audience, Part 2: More Tips and Tricks?

Agenda

Slide37

Our team uses a collection of common keys defined in a series of “resources” maps.

Company names

Product namesTerminologyLinks to AIR websitesWhen converting content from Word to DITA or when creating new content, writers must convert literal strings to the corresponding

<keyword

keyref

=“

[appropriate key]

”/>

Schematron Quick Fixes – What are they?

Slide38

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.Schematron Quick Fixes – What are they?

Slide39

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/schematron-quick-fixes-x-editing2.html

)

Schematron Quick Fixes – What are they?

Slide40

Schematron Quick Fixes – What are they?

Slide41

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

Configure the Oxygen DITA extension to recognize the rules file.

You or each writer can enable automatic validation using this rules file.