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

1. Integrating content?
Minimalize, downsize and
make it DITA compliant!
Marie-Louise Flacke
Information Developer
Congility Conference
2011, Crawley, UK

2. What and how to integrate?
GIGO?
Full content ?
Copy & paste?

3. Process
•
.
Analyze
•
Clean
•
Re-write
•
Test
•
Hand-over

4. Analyse legacy documents
•
.
Find the tasks?
•
Explicit topic titles?
•
Acronyms defined ?
•
Graphics quality?
•
Text about text?

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. Start Cleaning
(3) Glue
• Stem sentences
• Prepositions/adverbs/adjectives
(4) Useless signs
• Warnings
• Notes

7. Cleaning: don‘t insult
(5) … User‘s intelligence !
This is a warning
sign!

8. Objective: DITA
DITA compliant?
Legacy
documentation

9. Task vs. Useless title
7.1 Voice recording playback

10. Task: Sort the trash!
7.1 Voice recording playback

11. Task = title
<TITLE> Changing the scanner settings
<TITLE> Setting up a different scanner
<TITLE> Testing and repairing a scanner

12. Define Acronyms!
•
ATM?
•
Air-Traffic Management
•
Asynchronous Transfer Mode
•
Automatic Teller Machine
• … what else ?

13. Redundant
graphic?

14. Screenshots

15. Pictograms, logos…

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. Text about text
.

18. Getting more and
more DITA
compliant…

19. Organize!

21. 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.

22. Stop playing with
warning signs!

23. Even more DITA
compliant…

24. 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

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

26. Title, warning, note?

28. Grouping?
Title?
Note?

29. 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++

30. 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

31. DITA ready: Hand-over to the migration team!
Documentation
volume – 50%
High re-use
rate
Localization
costs – 80%

32. minimalist-doc.blogspot.com
Tel. : +33 9 75 75 40 20
GSM: +33 6 03 20 50 10
Contact : flacke[at]orange.fr