This project was started in 2011. Optimarin approached W2U and explained that they had a lot of Word documents and a high volume of the content was shared in all documents. But due to the nature of Word, they could not achieve any single sourcing. Optimarin thought that there must be single sourcing tools out there and searched the internet. Along came Madcap and the rest is history. Read the case study to see how Optimarin could still fulfill the need for individual manuals for each client without compromising the single sourcing concept of the project.
2. Speaker Bio
• Owner and founder of Write2Users (W2U)
• Technical Writer since 1991
• Localization Manager since 1997
• Software trainer since 1997
• Webmaster from 2000 – 2009
• Switched from Robohelp to Flare in 2006
• Certified Madcap Trainer and Consultant
• Highly Commended Award in eHelp Online
Help competition
• Runs the Technical Communication
Workshop worldwide with partner Mette
Nyberg from Schneider Electric, Denmark
3. • Customer is Optimarin AS from Norway
• Pioneers in ballast water systems for ships and vessels
• New rules require this type of system onboard any vessel
• Each vessel has a customized system onboard (components,
dimensions, etc.)
• Each vessel has its own unique manual
Customer Case
4. • Copy/paste is dead – single sourcing rules
• Too many style and table variants in Word source files
• Word graphics with callouts require localization
• Very big matrix of sales options – components, suppliers, etc.
• Unique front page for each manual
• Requirement: One target for all manuals
Challenges
5. Overview
Topic Word Flare
Manuals (PDF) Now: 60
Soon: 200
Now: 60
Soon: 200
Online help None Soon available
Tables Many variants 4 table styles
Styles 100+ 20-30
Single sourcing
Text None –
copy/paste
Snippets,
conditions,
variables
Images Common
repository
Common
repository
Database None One Flare target
and client
frontend
6. Word Import
Mark up styles
in Word
print version
Create new
stylesheet in
Flare
Test style
mapping in
Flare
Word file
cleanup
Test and re-test
Word Import
Import into
Flare and cut
cord to Word
7. Flare Stylesheet
Focus on PDF
This is the primary output
for the customer.
Notice that font sizes for
h1, h2, etc. are in %.
Prepared for online
The stylesheet is
prepared for HTML5
output. All other style
sizes are relative to 11 pt.
8. Style Mapping
Many style variations
The Word file had many
style variations.
Style mapping
Numerous variations
collapsed in Flare and made
style mapping possible.
9. Search and Replace
Our recommendation
Make the switch to Flare as early as
possible. You can stay in Word forever to
prepare for a clean Flare import.
First steps
Analyze the print version armed with a
highlight marker. Mark up all instances of
recurring replacement candidates.
Examples:
• Heading numbering
• Incorrect/Inconsistent use of styles
• Unwanted line and page breaks
• Text inside images 1. Start with standard
search/replace operations.
2. Continue with search/replace
based on regular expressions
The style attribute is redundant.
It’s part of the style in Flare.
10. Regular Expressions
Replacement candidates
• Word lists (bullets/numbers)
• Table of Contents
• Heading numbering
• Remove Word bookmarks –
this example
Expresso –
Regular
Expressions
builder
This tool allows
you test your
regular
expressions
before launching
them.
11. Table Styles
Many table variations
We managed to boil it down
to four different table styles.
Table styles
Word has no table styles, so
they must be applied
manually. Use Apply Style.
Local changes are defined
in table stylesheet.
12. Snippets
How it works
We’ve combined the
invisible.css table style with
a snippet.
Inserting the warnings
Type the first letters of the
word to insert the snippet.
Right-click and convert to
text, then edit the text.
13. Conditions - images
Apply conditions directly in the topic
1. Right-click the image and select
Conditions.
2. Apply the relevant PICT_ condition.
Images for conditions
We are using four images
to show the images for the
six sales versions.
Six sales versions
BK – FX – FS
Plus the above with
Stripping
14. Conditions - text
Apply conditions directly in the topic
1. Select the relevant text. In this example,
the FX column header is selected.
2. Press CTRL+SHIFT+C and apply the
relevant USE_ condition.
Apply conditions to TOC items
1. Select the topic in the TOC.
2. Press F4.
3. Click the Conditional Text tab.
4. Select the relevant USE_
condition.
15. Front page
Global and target-
specific variables
Link to: cover.png
Image is taken from
repository of images and
copied/renamed at build
time.
Uses Page Layout -
Cover
16. Front page
Page Layout
The break between body (1) and body (2)
controlled with a column break.
Topic – Cover.htm
Preview of print topic.
17. Database solution
What we know …
• The manual content is determined by the
sales options purchased
• There are many sales options and many
combinations
• Each manual is unique
• Each front page is unique
• We must prepare for language versions
• Normal Flare use would result in hundreds
of targets
What we want …
• Optimarin users can produce a manual
based on the sales order
• Content must be maintained in one Flare
project
• Content and images must be
shown/hidden based on conditions
• A database solution which can create
specific manuals from one target and
save produced targets (for reuse)
18. Database solution
Our solution
1.
The user enters Flare target
settings and customer
information in a client frontend.
2.
Customer/sales information is
picked up from Dynamix and
sent to the database.
3.
The database information is
injected into the target file.
4.
The target file is built
automatically and notifications
will be sent by e-mail.
19. HTML5 output
• The project is prepared for HTML5 output
• Not the primary format for the end user (PDF)
• Very relevant for internal use and technical support –
they will have access to the entire documentation
• With minimal changes to the CSS and a new master page,
the HTML5 output is not far away
20. Lessons learned
Process Conclusions
Styles Create a new CSS in Flare and profit from the hierarchical
nature of stylesheets. Also applies to well-structured Word
files.
Word
cleanup
Only clean up obvious mistakes like incorrect styles in Word.
The open nature of Flare source files makes it easy to clean
up code later on. Cut the cord and don’t go back!
Regular
Expressions
Can be used for advanced search/replace operations.
Use tools like Notepad++, TextPipe and Expresso.
Single
sourcing
It’s possible to go beyond Flare’s native single sourcing
capabilities. Used to minimize the number of targets in this
project.
Conditions We were certain that boolean operators could solve our
challenge, but ended up with a standard condition setup.
Lesson learned – remember to think in alternatives.
Good afternoon! My name is Per Frederiksen. I’m the owner and founder of the Danish information company, Write2Users.
I’m very happy to be here in San Diego to meet the Madcap community. I’ve been working as a Madcap reseller, trainer and consultant since 2010 and I’m meeting many Madcap colleagues for the first time.
I’ve been involved in the technical writing industry since 1991. I started out in the medical equipment industry, moved on to the financial business and ended in industrial automation. Over the years, I’ve been working with PageMaker, Interleaf, Framemaker, Robohelp, before I moved on to Flare in 2006.
In parallel with technical writing, I’ve been responsible for software and documentation translations into 10 languages.
I’ve been a training instructor since 1997 designing classroom training, online training and from 2008 produced many training videos using Camtasia Studio.
My involvement in websites has given me a good insight into usability, analyzing user behavior and being responsive to user requests.
Today I’m going to present a customer case which I think would be interesting for people considering importing Word content into Flare.
My goal for this presentation is to share best practices and tips for importing Word content into Flare.