Make the move from basic documents to structured documents

Bernard Aschwanden
www.publishingsmarter.com
bernard@publishingsmarter.com
Make the Move
Unstructured to Structured
14:04
1
@aschwanden4stc #stc19

Migrating Word to FrameMaker to Structure
14:04@aschwanden4stc #stc19
2
 Word is great when you have content that is managed by
SharePoint, or based on standard and highly-enforced
templates, or you have a team of developers to support
your team of writers. However, there are too many ways
for too many people to cause too many problems. Style
overrides, manual formats, or just incorrect use of a
template can haunt good content. You spend time and
effort to make content great; now put a little bit more time
into getting to know a tool that isn’t created for everyone.
It’s created for those of us who work in technical
communication. It’s time for Adobe FrameMaker.

Overall Objectives
3
 Evaluate a Word document for content quality
 Rework content for a topic-based model
 Import a Word file to Adobe FrameMaker
 Create a structured workflow
 Migrate legacy content to a structured format
 Move your content to a CCMS
 Publish single sourced content to multiple channels,
formats & devices

Rule 1: Know your audience
4
 Why are you here? (A bit of a “show of hands”)
 Free certificate that I can use to get a raise at work?
 Here because “my boss made me do it”?
 Here because migrating to structure is something you
 Are just starting to talk about?
 Want to do in the next 6 to 12 months?
 Love it more than almost anything else on earth and you need it yesterday?
 Prerequisite is a basic familiarity with content creation
 Who is planning to “play along” as we do the work?

Housekeeping and note taking
 Not all slides or topics are
equally weighted
 Use some, discard others
 Slides speed varies (reference)
 Questions? Ask along the way!
 I’d love to claim errors/typos is
on purpose… they isn’t,
weren’t never, and ain’t; I’ll fix
‘em as I can…
 Tweet using @AdobeTCS and
@aschwanden4stc
 Reference #stc19
5

About your speaker
 Publishing Smarter: President
 Content strategist, publishing
technologies expert, author,
and geek-enough
 Certified Technical Trainer
 FrameMaker
 Content management
 Topic-based writing
 Structured content (includes
DITA)
 Society for Technical
Communications
 Past President
 STC Associate Fellow
6

Standard disclaimer
 In the interest of brevity I
will make some blanket
statements to keep it simple
 It’s not all 100% “the truth”,
but I’ll stay close
 Purists may complain
 And they are wrong!
 (except when they are right)
 A lot of slides to guide us,
plus hands-on work
7

Some stuff you know, some tech you
may not, and some hands on work
Go ahead, launch Word now…
@aschwanden4stc #stc19 14:40
8
Evaluate a Word Document

We created 3 documents to quickly demo ideas
9

Mix and match: Sample 1—Poor styles
10

PDF of the“Poor”has weak/flawed bookmarks
11

Mix and match: Sample 2—Mixed styles
12

PDF of the“Mixed”has 6 (incorrect) bookmarks
13

Mix and match: Sample 3—Good styles
14

PDF of the“Good”has well-nested bookmarks
15

Before we go further
16
 Do you know if your content is well styled? (If so, how?)
 Do you think that there may be:
 Format overrides (to make that paragraph fit on a line, or the word
stand out, or the content fit on a page)
 Empty paragraphs (or even empty spaces that may have style info)
 A mix of manual and programmed references (see X on page #)
 Manual and automated numbering mixed together
 Content copied/pasted from other documents
 If so, then content may be a risk for conversion

Let’s talk about the *.docx extension
 It’s actually XML
 You can “unzip” DOCX
 Creates folders including
the /word folder
 document.xml
 styles.xml
 /media
 Each XML has info
 The document.xml is info
about the content including
overrides to formats
 The styles.xml is the actual
set of default styles that exist
 The media folder contains,
amongst other things, images
17

The process (defaults in Windows, no magic)
1. Create a *.docx file
2. Make a copy of it
3. Rename the copy to *.zip
4. Extract the zip file
5. Review content
We’ll look at the
document.xml file and
discuss the styles.xml
briefly.
18

document.xml from a good doc
19
 <w:p w:rsidR="003754B0" w:rsidRDefault="00391015"
w:rsidP="003754B0">
<w:pPr>
<w:pStyle w:val="Title"/>
</w:pPr>
<w:r>
<w:t>Prepping a Word Document for
Structure</w:t>
</w:r>
</w:p>

document.xml from a mixed doc
20
 <w:p w:rsidR="003754B0" w:rsidRDefault="00615507"
w:rsidP="00A3480A">
<w:pPr>
<w:jc w:val="center"/>
</w:pPr>
<w:r>
<w:t>Prepping a Word Document:
Mixed</w:t>
</w:r>
</w:p>

document.xml from a poor doc
 <w:p w:rsidR="0056B"
w:rsidRPr="0017024B"
w:rsidRDefault="00433EC2"
w:rsidP="00445B46">
<w:pPr>
<w:rPr>
<w:sz w:val="54"/>
<w:szCs w:val="54"/>
</w:rPr>
</w:pPr>
<w:r w:rsidRPr="0014B">
<w:rPr>
<w:b/>
<w:sz w:val="54"/>
</w:rPr>
<w:tab/>
</w:r>
<w:r w:rsidR="0014B">
<w:rPr>
<w:b/>
<w:sz w:val="54"/>
</w:rPr>
<w:t xml:space="preserve" />
</w:r>
<w:r w:rsidR="00FAC"
w:rsidRPr="0017024B">
<w:rPr>
<w:sz w:val="54"/>
</w:rPr>
<w:t>Prepping a Word
Document: Poor</w:t>
</w:r>
</w:p>
21

The good styles.xml defines character style
22
 <w:style w:type="character" w:styleId="Strong">
<w:name w:val="Strong"/>
<w:basedOn w:val="DefaultParagraphFont"/>
<w:uiPriority w:val="22"/>
<w:qFormat/>
<w:rsid w:val="00391015"/>
<w:rPr>
<w:b/>
<w:bCs/>
</w:rPr>
</w:style>

styles.xml also defines table style
23
 <w:style w:type="table" w:default="1" w:styleId="TableNormal">
<w:name w:val="Normal Table"/>
<w:semiHidden/>
<w:unhideWhenUsed/>
<w:qFormat/>
<w:tblPr>
<w:tblInd w:w="0" w:type="dxa"/>
<w:tblCellMar>
<w:top w:w="0" w:type="dxa"/>
<w:left w:w="108" w:type="dxa"/>
<w:bottom w:w="0" w:type="dxa"/>
<w:right w:w="108" w:type="dxa"/>
</w:tblCellMar>
</w:tblPr>
</w:style>

styles.xml also has paragraph style (+bonus!)
24
 <w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="heading 1"/>
<w:basedOn w:val="Normal"/>
<w:next w:val="Normal"/>
<w:link w:val="Heading1Char"/>
<w:qFormat/>
<w:rsid w:val="003754B0"/>
<w:pPr>
<w:keepNext/>
<w:keepLines/>
<w:spacing w:before="240" w:after="0"/>
<w:outlineLvl w:val="0"/>
</w:pPr>
</w:style>

What this means for you
25
 You can create Word files with or without overrides
 You can create a zip and extract/analyze the XML
 Look for things like:
 w:pStyle
 w:style w:type="character“
 w:style w:type=“table“
 w:p (this is the default “Normal” tag)
 Reference the Microsoft materials and other content for details
 Get Hands On: Let’s create a Word file now
 Launch Word and File > New to create a generic file

The goal is to build this (Details follow)
26

Initial content to write (no format, just text)
27
Moving to structured content¶
The move to structured content is gaining a lot of traction.¶
There are many reasons, including:¶
Working with large volumes of content¶
Managing complex numbering systems¶
Meeting online or print design and layout requirements¶
Publishing to Responsive HTML5 (plus apps, ebooks, and
PDF), or¶
Other reasons to retire just a word processor and use a
professional communications tool!

Next steps (add formats)
28
Moving to structured content [Assign Title, +Center Button]
The move to structured content is gaining a lot of traction. There
are many reasons, including: [Make 2 words Emphasis]
 Working with large volumes of content
 Managing complex numbering systems
 Meeting online or print design and
layout requirements
 Publishing to Responsive HTML5
(plus apps, ebooks, and PDF), or
 Other reasons to retire just a word processor and use a
professional communications tool!
[Make the rest of the
paragraphs bulleted;
select them all, then
click the toolbar icon]

Save the file as“MoveToStructure.docx”
29
Title paragraph
(+manual center)
“Normal” paragraph
with 2 words in
Emphasis
Collection of bullets
(using the toolbar icon)

Behind the scenes (the XML you could extract)
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:document xmlns:ve="http://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"
xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
xmlns:w10="urn:schemas-microsoft-com:office:word"
xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml">
<w:body>
<w:p w:rsidR="008E34F2" w:rsidRDefault="00AA6835" w:rsidP="00A801F8">
<w:pPr>
</w:pPr>
<w:r>
<w:t xml:space="preserve">Moving to structured </w:t>
</w:r>
<w:r w:rsidR="00A801F8">
<w:t>content</w:t>
</w:r>
</w:p>
<w:p w:rsidR="00AA6835" w:rsidRDefault="00AA6835" w:rsidP="00AA6835">
<w:r>
<w:t xml:space="preserve">The move to </w:t>
</w:r>
<w:r w:rsidRPr="00AA6835">
<w:rPr>
<w:rStyle w:val="Emphasis"/>
</w:rPr>
<w:t>structured content</w:t>
</w:r>
<w:r>
<w:t xml:space="preserve"> is gaining a lot of traction. There are many reasons, including:</w:t>
</w:r>
</w:p>
<w:pPr>
<w:pStyle w:val="ListParagraph"/>
<w:numPr>
<w:ilvl w:val="0"/>
<w:numId w:val="1"/>
</w:numPr>
</w:pPr>
<w:r>
<w:t>Working with large volumes of content</w:t>
</w:r>
</w:p>
 <w:p w:rsidR="00AA6835" w:rsidRDefault="00AA6835" w:rsidP="00AA6835">
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/>
</w:numPr>
</w:pPr>
<w:r>
<w:t>Managing complex numbering systems</w:t>
</w:r>
</w:p>
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/>
</w:numPr>
</w:pPr>
<w:r>
<w:t>Meeting online or print design and layout requirements</w:t>
</w:r>
</w:p>
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/>
</w:numPr>
</w:pPr>
<w:r>
<w:t xml:space="preserve">Publishing to Responsive HTML5 (plus apps, </w:t>
</w:r>
<w:proofErr w:type="spellStart"/>
<w:r>
<w:t>ebooks</w:t>
</w:r>
<w:proofErr w:type="spellEnd"/>
<w:r>
<w:t>, and PDF), or</w:t>
</w:r>
</w:p>
<w:p w:rsidR="00AA6835" w:rsidRPr="00AA6835" w:rsidRDefault="00AA6835" w:rsidP="00AA6835">
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/>
</w:numPr>
</w:pPr>
<w:r>
<w:t>Other reasons to retire just a word processor and use a professional communications tool!</w:t>
</w:r>
</w:p>
<w:sectPr w:rsidR="00AA6835" w:rsidRPr="00AA6835" w:rsidSect="008E34F2">
<w:pgSz w:w="12240" w:h="15840"/>
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720"
w:footer="720" w:gutter="0"/>
<w:cols w:space="720"/>
<w:docGrid w:linePitch="360"/>
</w:sectPr>
</w:body>
</w:document>
30

The details you may care about…
<w:body>
<w:p w:rsidR="008E34F2"
w:rsidRDefault="00AA6835" w:rsidP="00A801F8">
<w:pPr>
</w:pPr>
<w:r>
<w:t xml:space="preserve">Moving to structured
</w:t>
</w:r>
<w:r w:rsidR="00A801F8">
<w:t>content</w:t>
</w:r>
</w:p>
<w:p w:rsidR="00AA6835"
w:rsidRDefault="00AA6835"
w:rsidP="00AA6835">
<w:r>
<w:t xml:space="preserve">The move to </w:t>
</w:r>
<w:r w:rsidRPr="00AA6835">
<w:rPr>
<w:rStyle w:val="Emphasis"/>
</w:rPr>
<w:t>structured content</w:t>
</w:r>
<w:r>
<w:t xml:space="preserve"> is gaining a lot of
traction. There are many reasons, including:</w:t>
</w:r>
</w:p>
<w:p w:rsidR="00AA6835"
w:rsidRDefault="00AA6835" w:rsidP="00AA6835">
<w:pPr>
<w:numPr>
<w:ilvl w:val="0"/>
</w:numPr>
</w:pPr>
<w:r>
<w:t>Working with large volumes of
content</w:t>
</w:r>
</w:p>
31

Diving deeper
/* Get Word DOCX Statistics
// Prompt for Word files.
// Set up an output file.
// Get the files to process.
// Process all files.
// Write the file statistics
// Append the field list
// Get the number of pages.
// Add tables's style data
// Generate the report
// Format it all for Excel
 Remember our 3 Word files?
 We decided to go explore them
 Using our own tools we converted
each of the three “sources” to XML
 We can ID what is in the XML
 Consolidate info into a spreadsheet
 Can be done file by file
 We ended up automating it
32

Analytics initially show 3 similar docs…
33

… but the details show very different results
34

Just character level details are scary (poor)
35

The details remain scary (mixed)
36

The details are scary (but less so in the good)
37

Content cleanup tips
38
 We can find very detailed issues
 Track them down
 Fix them “one-by-one” or ID when it makes sense to do it
programmatically
 The tricky part kicks in with larger doc sets
 Hundreds, or even 1000s of source Word documents

For example, with many documents
39

Once you know the volume and types of issues
40

Legacy content review
41
 Please feel free to ask me about your own content later on
 bernard@publishingsmarter.com
 ENSURE YOU CAN ACTUALLY SHARE IT (legal/NDA)
 I’m also at the Adobe booth for the conference
 Mention the STC conference and the Adobe workshop

Making the move to modular topics
may mean rewriting legacy content
42
Rework content for a
topic-based model

 Modular means:
 Pieces of information must
make sense without context
 Pieces of information can
be moved around
 Context may or may not
bring extra meaning to
individual pieces
15:03
43
@aschwanden4stc #stc19

Benefits of topic-based content for users
44
 Read what you want
 Read in the order you want
 Common layout makes it fast to scan and find content
(beyond search)
 Right information, right format, right time
 Information is in topic types, each with a purpose
 Task: How to complete a goal
 Concept: Why a goal is worth achieving, or what it is
 Reference: Quick lookup or guide to technical specs

Review your materials for nested content
45
Learning’s complex enough
 Use titles that relate to the goal of a
user
 Don’t nest additional steps or tasks
 Rework content into clear topics
Saving
1. Select File > Save As
The Save dialog appears.
2. Select a location
3. If required, create a folder
a) Click New Folder
A new folder is created
b) Type a name for the folder
c) Press Enter
4. Choose a file format
 RTF: Rich Text Format
 DOC: Microsoft Word document
 FM: Adobe FrameMaker file
5. Name the file and click Save.

Save a file Create folders to organize files
1. Select File > Save As
2. Select a location
3. Choose a file format
4. Name the file
5. Click Save
1. Click New Folder
2. Type a name for the folder
3. Press Enter
Much better would be
46

 Darwin Information Typing Architecture
 DITA is about Topic, Maps, Specializations
 Some common topic types include
 concept
 reference
 task
 glossary
 bookmap and map
47
DITA supports topic-based content
DITA Information Types
Topic–Concept–Task–Reference

Types of topics
48
 Tasks: Start with tasks (Users don’t want to
learn about something unless they have to)
 What does the user need to do? Identify those and
then write how they do it.
 Concepts: Supporting info for a task
 In many cases, concepts can provide a clear
conceptual model that is lacking in a task. Used to
orient the users.
 References: Quick look up; no procedures,
no conceptual information

Work with images: Text heavy, mixed source
It has been said a picture is worth
1000 words. If this is true, it
makes sense to use images to
show ideas, visualize things, or to
add life to dry text. You can add
images in supported formats to
web pages.
To insert images first select
where you want in on your web
page. Choose Insert in the Image
menu. There are many image
formats supported (web formats),
and since pictures draw the eye
to a specific location, you may
want to add maps or charts.
If maps or charts are used they
can visually explain ideas that
may take many pages to write
about. They can even make
content feel more alive, so if it
makes sense, add them to reports
to accentuate an idea that
matters.
Once you know the format you
need, select a file location and
click Map or Chart if needed. We
support jpg, gif, png, svg (and we
convert Illustrator or Photoshop
too!). Click on a file, then Insert.
49

ID the task / concept / reference?
web pages.
matters.
50

Remember: Tasks come first
web pages.
matters.
51

Repeat for concepts
web pages.
matters.
52

And for references
web pages.
matters.
53

Consider using highlighters!
54

Now, the task title reads: Import pictures
55
Images, maps, and charts can be added to web
pages.
Prereq: Ensure graphics are in a supported
web-friendly file format.
1. Select the location to insert an image.
2. Select Image > Insert.
If inserting a Map or Chart, specify this.
3. Select a folder location.
4. Select a file.
5. Click Insert.
6. Configure the image as needed.

Concept title: Reasons to use pictures
56
It has been said a picture is worth 1000 words;
use images to show ideas, visualize complex
ideas, or to add life to dry text.
Pictures draw the eye to a specific location. If
maps or charts are used they can graphically
explain an idea that may take many pages to
write about. They can even make content feel
more alive, so if it makes sense, add them to
reports to accentuate an idea that matters.

Reference title: Supported image formats
57
Graphic types, how they are used, and
background information.
Format Function Notes
.jpg Raster based
images displayed
online (web).
Our conversion tools allow
multiple options, test for best
compatibility.
.gif
.png
.svg Vector based
images displayed
online (web)
Our conversion tools allow
multiple options, test for best
compatibility.
.ps Adobe Photoshop Raster based source.
.ai Adobe Illustrator Vector based source.

Remember: Styles are your friends
58
Import a Word file to FrameMaker

Importing Word to FrameMaker
 Styles can be mapped
 Once mapped, save it
 Import one or more *.docx
 Results vary
 Better results
 Better styles in the source
 Better use of the styles
 Poorer results
 Poor use of styles
 Misuse of styles
59

Poor document mapped may look like
60

Mid range
61

Good document mapped may look like
62

Importing our Word document
1. Launch FrameMaker
2. Select File > New >
Document, then Portrait
3. Select File > Import > File
4. At the bottom, click
Copy Into Document
5. Find/select the Word
source
6. Import the document
7. Confirm message dialogs
63

Configure the import
64
 FrameMaker scans the Word source document
 If styles in Word match tags in FrameMaker they are
automatically mapped for you
 If they do NOT then you can map them via a visual
interface
 Character format and table format conversion can be done
 Advanced settings allow for further cleanup
 You can even save your settings
 Demo: Configure the dialog as seen on the next slide

Configure your settings, then click OK
65

Save the file
66

Launch FrameMaker and create your
first structured content
67
Create a Structured Workflow

Look for Element and Structure in Menu
68

If NOT, select Edit > Preferences
69
1
2
3

Optional relaunch File > New > DITA > Concept
70

By default you see this (or similar)
71

Change to a structured author mode
72
1
2

Structure View: Hierarchy of content
73

Click to the right of an element and type
74

Save and Close the file
75

Our imported Word source can be
converted to structured, DITA-ready
content with a bit of setup
76
From Legacy to Structure

Big picture for conversion
77
 Any content in FrameMaker can be converted
 The more complex the content, the tougher the setup
 We have a basic document
 Title paragraph
 Body paragraph
 Bulleted paragraphs
 Emphasis character format
 Our conversion table basics are just that… Basics

Open MoveToStructure.fm
78

Structure > Utilities > Generate CT
79

Structure > Utilities > Generate CT
80

Generate a New Conversion Table
81

A bit of detail on the columns
82
Wrap this object or objects In this element With this qualifier
P:Title Title
P:Body Body
P:Bulleted Bulleted
C:Emphasis Emphasis
When a P (paragraph) or C
(character) with a name is
found...
...take that tagged
content and wrap it
into a named element

Save as CT-BasicConcept.fm
83
P:Title Title
P:Body Body
P:Bulleted Bulleted
C:Emphasis Emphasis

Update to names DITA likes
84
P:Title title
P:Body p
P:Bulleted li
C:Emphasis i

Nest elements
85
P:Title title
P:Body p
P:Bulleted li
C:Emphasis i
E:li+ ul
(E:p | E:ul)+ conbody
E:title, E:conbody concept

Apply the Conversion Table
1. Go to MoveToStructure
2. Structure > Utilities >
Structure Current Doc
3. Choose the CT file
4. Click Add Structure
5. Click OK
6. Review the structure
86

Once converted to structure (and based on DITA)
 The content could be
copied into a DITA concept
 Once there, a bit of minor
cleanup
 For example, you may choose
to click View menu and show
or hide boundaries to dive in
deeper, or change attribute
display options
 May want to “right-click” the
concept element and assign
an ID
 Regardless of additional
changes, the core of the
conversion is complete
 The file can quickly be
converted to DITA
 If the source has more
paragraphs or bullets
added, re-run the CT
 If more objects are added,
the CT needs more dev
87

Good Word, when mapped, may import as…
88

Migrating Frame to DITA
89

What a Structured (DITA) file looks like
90

Remember the Good, the Bad, and the
Ugly
91
Move content to a CCMS

Good topic-based content is standard content
92

Live? Video? Slides?
93
 Going to try it live because…
 I’m an idiot?
 Hotel networks are 100% reliable and fast?
 I tested this extensively?
 If it WON’T play nice I have a backup in Captivate
 Let’s go…

PDF, HTML5, and other formats
94
Publishing

FrameMaker offers PDF/HTML5, etc File > Publish
95

But… Word also converts to PDF and HTML
96

Yeah. About that.
97

Oh. Look. Word to HTML
98

PDF from FrameMaker
99

HTML5 from FrameMaker
100

Summary and next steps
101
Conclusion

In about 75 minutes we did this:
102
 Evaluate a Word document for content quality
 Rework content for a topic-based model
 Import a Word file to Adobe FrameMaker
 Create a structured workflow
 Migrate legacy content to a structured format
 Move your content to a CCMS
 Publish single sourced content to multiple channels,
formats & devices

Download the whitepaper Watch the videos
103
https://tinyurl.com/PS-YouTube-FM-Structure
https://tinyurl.com/PS-Adobe-Structure-Migration

Services
104

Follow up contact information
105
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwanden
www.publishingsmarter.com

Make the move from basic documents to structured documents

Recomendados

Recomendados

Más contenido relacionado

Similar a Make the move from basic documents to structured documents

Similar a Make the move from basic documents to structured documents (20)

Más de Publishing Smarter

Más de Publishing Smarter (20)

Último

Último (20)

Make the move from basic documents to structured documents