Integrating content?
Minimalize, downsize and
make it DITA compliant!

Marie-Louise Flacke
Information Developer

Congilit...
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?

•
...
Start Cleaning
(1) Decorum
• Eliminate frames
• Eliminate unnecessary graphics
(screenshots, pictograms, icons)

(2) Pompo...
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
DITA compliant?

Legacy
documentation
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 ...
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 R...
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...
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… C...
Minimalism
•
•
•
•

Garbage-free
Structured
Optimized (for migration)
Re-usable
Title, warning, note?
Grouping?
Title?
Note?
Eclipse and CDT (continued)
1.1 Run the Eclipse and CDT installation for Windows

The CDT software is required if you are ...
Entering text
1. Start programming with the TM/ST key
2. Press the job code number
3. Press the XYZ key.
The cash register...
DITA ready: Hand-over to the migration team!
Documentation
volume – 50%
High re-use
rate

Localization
costs – 80%
minimalist-doc.blogspot.com
Tel. : +33 9 75 75 40 20
GSM: +33 6 03 20 50 10
Contact : flacke[at]orange.fr
Migrating to  dita_ flacke
Migrating to  dita_ flacke
Prochain SlideShare
Chargement dans…5
×

Migrating to dita_ flacke

637 vues

Publié le

Technical documentation: Before migrating your files to DITA, you should clean them and eliminate redundant and unnecessary content: meta-text, stem sentences, useless 'general information', etc. - Provide clear, concise, user-friendly procedures - Skip useless screenshots and warning messages

Publié dans : Marketing, Technologie
0 commentaire
1 j’aime
Statistiques
Remarques
  • Soyez le premier à commenter

Aucun téléchargement
Vues
Nombre de vues
637
Sur SlideShare
0
Issues des intégrations
0
Intégrations
2
Actions
Partages
0
Téléchargements
8
Commentaires
0
J’aime
1
Intégrations 0
Aucune incorporation

Aucune remarque pour cette diapositive
  • IBM Rhapsody installation Guide, 2009
  • The first note was located page 20 (original located page 5)
  • Migrating to dita_ flacke

    1. 1. Integrating content? Minimalize, downsize and make it DITA compliant! Marie-Louise Flacke Information Developer Congility Conference 2011, Crawley, UK
    2. 2. What and how to integrate? GIGO? Full content ? Copy & paste?
    3. 3. Process • .  Analyze • Clean • Re-write • Test • Hand-over
    4. 4. Analyse legacy documents • .  Find the tasks? • Explicit topic titles? • Acronyms defined ? • Graphics quality? • Text about text?
    5. 5. 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… )
    6. 6. Start Cleaning (3) Glue • Stem sentences • Prepositions/adverbs/adjectives (4) Useless signs • Warnings • Notes
    7. 7. Cleaning: don‘t insult (5) … User‘s intelligence ! This is a warning sign!
    8. 8. Objective: DITA DITA compliant? Legacy documentation
    9. 9. Task vs. Useless title 7.1 Voice recording playback
    10. 10. Task: Sort the trash! 7.1 Voice recording playback
    11. 11. Task = title <TITLE> Changing the scanner settings <TITLE> Setting up a different scanner <TITLE> Testing and repairing a scanner
    12. 12. Define Acronyms! • ATM? • Air-Traffic Management • Asynchronous Transfer Mode • Automatic Teller Machine • … what else ?
    13. 13. Redundant graphic?
    14. 14. Screenshots
    15. 15. Pictograms, logos…
    16. 16. 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)
    17. 17. Text about text . 
    18. 18. Getting more and more DITA compliant…
    19. 19. Organize!
    20. 20. 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.
    21. 21. Stop playing with warning signs!
    22. 22. Even more DITA compliant…
    23. 23. 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
    24. 24. Minimalism • • • • Garbage-free Structured Optimized (for migration) Re-usable
    25. 25. Title, warning, note?
    26. 26. Grouping? Title? Note?
    27. 27. Eclipse and CDT (continued) 1.1 Run the Eclipse and CDT installation for Windows The 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 XXX 2. 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++
    28. 28. Entering text 1. Start programming with the TM/ST key 2. Press the job code number 3. Press the XYZ key. The cash register is ready for text entry
    29. 29. DITA ready: Hand-over to the migration team! Documentation volume – 50% High re-use rate Localization costs – 80%
    30. 30. minimalist-doc.blogspot.com Tel. : +33 9 75 75 40 20 GSM: +33 6 03 20 50 10 Contact : flacke[at]orange.fr

    ×