Migrating from Unstructured Agenda
to Structured FrameMaker
Reviewing structure implementation
The FrameMaker structured application
Sarah O'Keefe Conversion rules tables
Scriptorium Publishing Eternal mysteries
www.scriptorium.com Resources
2
About those blank slides... Why structure?
No, I didn't forget to fill them in. Must move to Linux/can't use FM any more
I'm looking for audience participation on repurpose content for web/print
these slides. DITA? unified schema
reduce reliance on proprietary tools (get rid
of ePublisher Pro)
it might increase efficiency?
future-proof my content
company-driven...buzz
3 4
Reviewing structure
Why structure?
implementation
automated content generation Twelve-step process
no more reinventing the wheel Work in FrameMaker begins in step five
streamline data exchange/localization
RH>>languages/XML easier
distributed team
enforce template
easier content sharing
5 6

Implementation effort
DITA?
(a twelve-step process)
1. Identify implementation 7. Set up output paths. standard
goals. 8. Develop documentation.
2. Define roles. content reuse?
9. Deliver training.
3. Establish timelines. 10.Convert legacy documents. topic-based organization
4. Perform structure analysis. 11.Create change predefined architecture (no content
5. Create structure definition management process. modeling?)
files. 12.Provide transition support What if your content doesn't match?
6. Set up legacy conversion and validate
process. implementation. role-based content/conditionalization
7 8
What makes FrameMaker a
good choice for structure?
<topic customer=\"a,c\" platform=\"win\" structure view
output=\"online\"> print preview/visual editor
... already have it
</topic> lower learning curve?
really nice PDF/easy to create and format
authoring/publishing in one package
going to be around for a while
9 10
What makes FrameMaker a What are FrameMaker's
good choice for structure? disadvantages?
other people don't have it
print oriented
author mindset
configuration
configuration is difficult
...conversion of legacy content is horrid
no specialization support for DITA
predefined DTD requirement?
11 12

Creating an element definition
EDD syntax
document (EDD)
Pattern language programming Element specification syntax same as in
EDD is a structured FrameMaker file DTDs
Learning structured authoring while ? (question mark) – zero or one
creating an EDD is quite challenging * (asterisk) – zero or many
+ (plus) – one or many
, (comma) – sequence of elements
| (pipe) -- Or
( ) (parentheses) – for grouping
13 14
EDD creation process Element types in the EDD
Elements and attributes first Containers
Then add formatting Text range (character tag equivalent)
Cross-references
Markers
Variables
Graphics
Table components
15 16
What is the best formatting
Formatting choices in your EDD
approach?
Reference paragraph/character tags Downstream, ePublisher Pro requires
Format change lists paragraph/character tags.
Embedded formatting Using an existing formatting template will
save development time.
Format change lists allow inheritance.
Embedded formatting and format change
lists are harder for authors to modify.
17 18

What is the best formatting
Structured application
approach for you?
A set of configuration files
Not a “software application”
“An application of structure” to a particular
problem
19 20
FrameMaker structured
Basic structured application
application components
Element definition Read/write rules
document (EDD) Extensible
Formatting Stylesheet
template Language (XSL)
Document type transformation files
definition (DTD) or FrameMaker
schema file Developer's Kit
structapps.fm file (FDK) code
21 22
Real-life structured application Read/write rules vs. XSL vs. FDK
Difference is not always clear.
Read/write rules
FrameMaker-specific items, such as table
XSL widths or graphic attributes
FDK
XSL
Rearranging, reordering, filtering content
FDK
Things that are impossible with
23
read/write rules or XSL 24

FDK examples Good news/bad news
Automatic assignment of IDs and ID You can do almost anything with FDK
validation across a book. development.
Mapping of FrameMaker equation If your project requires FDK work, expect
information to MathML the cost to skyrocket.
Extraction of callouts from FrameMaker
anchored frame
Mapping of ID-based cross-references to
file-based linking (DITA)
25 26
Other bits...not technically part
FrameScript
of application
Conversion rules table for unstructured to Inexpensive
structured content conversion Will pay for itself on first project
FrameScript scripts for automation of No need to learn scripting; pay someone to
tedious tasks write the scripts
Document conversion
ePublisher Pro/MIF2GO
XSL transformation
27 28
Should you choose ePublisher
Conversion rules table
Pro or XSL transformation?
need XSL person/need ePP person Map unstructured components onto
stability of ePP elements
licensing of ePP Finally, a reward for virtuous tagging
need pretty cross-platform, cross-browser Don't expect 100 percent automation
help
XSL is faster
ePP is easier to configure/basics
29 30

What about DITA? Should you use DITA?
Darwin Information Typing Architecture 30% maybe, ??
Standard structure for modular no content modeling (only not)
documentation separate format vs. content (all XML)
FrameMaker has support for DITA built OOB authoring tool support
into version 8
widely known
hype
Easy enough even for technical writers (!)
What about DocBook?
31 32
The $64,000 question: How much
DITA?
will migration to structure cost?
software support Analyze content
topics are nice Research, choosing, configuring, buying
context-sensitive help? (Tony Self) software/tools
multiple outputs Write the business case
difficult to implement? (easier than the Get buy-in
alternatives??) (Re-)Training, learning new tools
vendor-independent? Conversion
Contractors/consultants
33 34
Cost Cost
Shift from not-topic-based to topic-based Turnover in staff
Technical support for configuration Change resistance
Additional tools Complexity
Productivity LOSS Upper management support/executive
CMS? sponsorship/\"eliminating\" change
resistance
Training
Personality issues/disruption/change Software change management
management M-O-N-E-Y
35 36

Cost Cost contributors
Ongoing training Number of authors
Transition plan Document complexity
Exit strategy (\"what if?\") Number of documents to be converted
Software support (vendor commitment) Degree of customization of structure
required
Number of deliverable types
Number of supported languages
Amount of training required
37 38
How much time will migration
Cost contributors
to structure require?
Complexity Not less than six months.
Velocity
39 40
What are the factors that affect
Size factors
implementation size?
Geography
In-house expertise and availability
Resources?
Who are the stakeholders?
41 42

Recommendations And random thoughts
DITA: Analyze how well DITA fits your Avoid FDK programming if possible to
content, then make a decision minimize costs.
FrameMaker for publishing: If you need Understand FrameMaker's object model
attractive print/PDF, FrameMaker is the and work within that model to simplify
way to go. development.
FrameMaker for authoring: If your existing If possible, start from FrameMaker
content is in unstructured FrameMaker, structure rather than from a DTD.
structured FrameMaker offers a gentler
path into XML-based authoring. Also
consider a mixed workflow. 43 44
Print challenges ePublisher Pro
FrameMaker provides excellent print and Use it if you need a format such as
PDF support. WebWorks Help
Most other structured workflows do not. If you have existing ePublisher Pro
The trade-off is that FrameMaker has templates, continue using them for the time
distinct preferences for your content being.
structure. To combine Word/FrameMaker/DITA
content, consider it.
Otherwise, switch to vanilla XSL
transformation.
45 46
XSL transformation
XSL-FO
for single sourcing
For generation of other markup (HTML) Extensible Stylesheet Language Formatting
from XML content Objects
Open standard Would replace FrameMaker for print
Parsers are free and open source production
If you can write scripts, you can write XSL FrameMaker is much easier to use and
produces nicer output
Learning curve is significant
Appropriate for batch processing, on-the-
fly generation of PDF, and other specialized
uses
47 48

Will you switch from
Localization
FrameMaker to XSL-FO?
for batch processing... Ship XML, not structured FrameMaker, to
for languages not supported in your localization vendor.
FrameMaker Build localized templates/structured
for Linux environments... applications/XSL transformation.
PDF is just a check-off Unicode now supported in v8.
No support for right-to-left languages
(Hebrew, Arabic).
49 50
Learning curve Final and most important issue
It's steep. Change resistance
Consider multiple training stages. Critical factor in determining success or
Divide and conquer failure of the entire effort
One person learns EDDs
One person learns XSL
Consultants can help.
51 52
Resources Resources
FrameMaker Developer Connection FrameScript, www.framescript.com
Structured Application Developer's Guide Rick Quatro, www.frameexpert.com, for
Migration white paper custom FrameScript development
www.adobe.com/devnet/framemaker/ XSLT Programmer's Reference, Michael Kay
Scriptorium web site (scriptorium.com) FrameMaker Developer's Kit, available
White papers from adobe.com
Structured FrameMaker training
Publishing Fundamentals: FrameMaker 7
(yes, we're working an update) 53 54

Contact information Q&A
Sarah O'Keefe
Scriptorium Publishing
www.scriptorium.com
okeefe@scriptorium.com
+1 919 481-2701 x102
55 56