Integrating content? Minimalize, downsize and

make it DITA compliant!

Marie-Louise Flacke

Information DeveloperCongility Conference 2011, Crawley, UK

What and how to integrate?

GIGO? Full content ?Copy & paste?

. 

Process

• Analyze

• Clean

• Re-write

• Test

• Hand-over

. 

Analyse legacy documents

• Find the tasks?

• Explicit topic titles?

• Acronyms defined ?

• Graphics quality?

• Text about text?

Start Cleaning(1) Decorum

• Eliminate frames

• Eliminate unnecessary graphics (screenshots, pictograms, icons)

(2) Pompous Text • Eliminate Text about text

• Eliminate general generalization (About, introduction, overview… )

Start Cleaning(3) Glue

• Stem sentences

• Prepositions/adverbs/adjectives

(4) Useless signs• Warnings

• Notes

Cleaning: don‘t insult(5) … User‘s intelligence !

This is a warning sign!

Objective: DITA

Legacy documentation

DITA compliant?

Task vs. Useless title

7.1 Voice recording playback

Task: Sort the trash!

7.1 Voice recording playback

Task = title

<TITLE> Changing the scanner settings

<TITLE> Setting up a different scanner

<TITLE> Testing and repairing a scanner

Define Acronyms!

• ATM?

• Air-Traffic Management• Asynchronous Transfer Mode• Automatic Teller Machine• … what else ?

Redundant graphic?

Screenshots

Pictograms, logos…

Stem sentences

• To introduce the steps in a task - steps won’t correctly start renumbering with 1)

(J.Hackos)

• Do We Really Need All that Glue? - transitional text, advance organizers, text between topics ?

(J. Hackos, DITA.xml.org)

. 

Text about text

Getting more and more DITA compliant…

Organize!

Warning = instructions

Cleaning the oxygen tubes

Make sure the oxygen tubes are fully clean.Oxygen, oil or grease make an explosive mixture.

1. Select the Maxi-brush 2. Perform a first cleaning with the Maxi-Brush 3. With the pressure-cleaner, perform a 2nd cleaning.

Stop playing with warning signs!

Even more DITA compliant…

Start Re-design/Re-design• Pertinent titles

• based on tasks

• Terminology & acronyms•Consistent, user-focused and… Controlled (English)

• Standardized procedures

•Convert notes & warnings in instructions

Minimalism

• Garbage-free • Structured• Optimized (for migration)• Re-usable

Title, warning, note?

Title?

Note?

Grouping?

1.1 Run the Eclipse and CDT installation for WindowsThe CDT software is required if you are developing in C and/or C++, but not for Java development.

1. Download the appropriate Windows version of Eclipse Ganymede from the site XXX2. Download the CDT software:

(a.1) Download the appropriate CDT version from the Site ZZZ(a.2) Follow the installation instructions on the site-or-(b.1) Inside Eclipse, select Help-->Software updates (b.2) Under the Available Software tab, select the appropriate CDT versioin(b.3) Follow the Eclipse installation instructions.

1.2 Add the language compilers • Select the compilers for the language/languages you are using.

1.3.Install the Rational Rhapsody Developer for C and/or C++

Eclipse and CDT (continued)

Entering text

1. Start programming with the TM/ST key2. Press the job code number3. Press the XYZ key.

The cash register is ready for text entry

DITA ready: Hand-over to the migration team!

Documentation volume – 50%

Localization costs – 80%

High re-use rate

Tel. : +33 9 75 75 40 20 GSM: +33 6 03 20 50 10

Contact : flacke[at]orange.fr

minimalist-doc.blogspot.com