XML authoring simplified for one and all: Writers UA

Bernard Aschwanden
www.publishingsmarter.com
bernard@publishingsmarter.com
XML Authoring Simplified
For One and All
15:11
1
@aschwanden4stc

Housekeeping
15:11@aschwanden4stc
2
 Thanks to Adobe and Joe for setting up this event
 In under 10 ideas (was slides, but I don’t want you to
write)
1. Setup of FrameMaker and create a bit of sample content
2. Overview of DITA in a single slide
3. Intro to all core topic types and elements
4. Behind the scenes (attributes)
5. Map
6. Concept
7. Task
8. Reference
9. Publish
10. Update/Publish again!

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)
 This can be interactive
 Raise a hand when asked
3

Many options exist, so let’s get onto
the same page (so to speak)
@aschwanden4stc 15:11
4
Setting up the software

1. Let’s standardize things: Edit >
Preferences
5
1
2
3

Enable Simplified XML (more on that later)
6
1
2
3

If needed, relaunch, then File > New > XML
7
1
2
3

By default you see this (or similar)
8

Change to a structured author mode
9 1
2

Structure View: Hierarchy of content
10

Element Catalog: Contextual list
11

Setup of a custom workspace (one time)
12
1
2

Collapse by double-clicking
13
1

Save your own workspace
14
1
2
3
4

Remove <related-links>
15
1

Add a title
16
1

Content in doc and in Structure View
17

Inline: View > Element Boundaries (as Tags)
18

Add content in tags, select/delete related-
links
19

View > Hide Element Boundaries
20

Save the file (anywhere, but make a folder)
21

2. Purpose of DITA
22
 According to me:
A formal, XML-based rule set for creating content
 Many people in tech comm already work with it
 DITA enables enhanced use of source content in a
vendor independent way
 At the same time, take advantage of work vendors
have already done!

2: Overview of DITA in a single slide
23
 Darwin Information Typing Architecture
 DITA is about Topic, Maps, Specializations
 Some specializations include
 concept, reference, task,
glossary (topic based)
 bookmap (map based)
 domains (software, programming)
 DITA 1.2 and 1.3 introduce more
based on the standard core topics
DITA Information Types
Topic–Concept–Task–Reference

3. Intro to core topic types and elements
24
Maps and bookmaps
• Used to plan, organize, and
publish
Reltables
• Build relationships between
topics in maps for enhanced
links
Topics
• Types of info in maps generally
a task, concept, or reference
Specializations
• Customize if other options are
exhausted: not using this today

4. Behind the scenes are attributes
25
Maps and bookmaps
• Used to plan, organize, and
publish
Reltables
• Build relationships between
info in maps
Topics
• Types of info in maps
generally a task, concept, or
reference
Specializations
• Customize as needed if other
options are exhausted
Attributes

4b. You likely already know about attributes
26
 Think about HTML
 <img src=“file.ext” height=“100” width=“200”>
 <a href="http://www.publishingsmarter.com">Think DITA!</a>
 In DITA it’s the same idea
 <note type=“tip”>Kids: Listen to your teacher; it’s worth
it!</note>
 <p audience=“novice”> or <p audience=“expert”>
 <p product=“Widget-o-matic”> or <p product=“Foo-blah-
bulator”>
 <cmd>Use the <ph platform=“win”>Explorer</ph>
<ph platform=“mac”>Finder</ph> to organize your
files.</cmd>

5. Use maps to organize info
27
 Maps organize topics; they are a bit like a master
document, book document, TOC, and site map
 They use <topicref> in a specific order to organize
info
 At publish time the order drives some functions (i.e.
TOC, related parent/child links)
 Making a map is easy
 At a high level, decide on primary goal
 Make that goal clear
 Add supporting content

5. Let’s build a New <map> in FrameMaker
281
2

File > Save Ditamap As... (m_DITA_and_FrameMaker)
29

Different views based on
preferences/functions
30

Change text? Double click snippets to select all
31

When content is selected, just type to edit
32

Let’s add the concept to the book
33

Add a <topicref> (a topic reference)
34

Double-click a file that already exists
35
1
2

So far, pretty simple, but a bit unimpressive
36

6. Concept explains ideas
 If people are wondering why
they should do something,
or the benefits, then a
concept is likely needed
 Answers the question what
is or why by detailing
information about
something
 Initial information that users
must know before they can
successfully work
 Supports the task by
providing an explanation
that is outside the scope of
the task
37

Key elements when getting started
38
 Before starting—common
elements I like:
 title is often a heading for the
topic, (also used by sections,
examples, figures, tables)
 shortdesc is an initial brief
statement in a topic that does
NOT repeat the title, it enhances
it
 prolog is metadata or information
about a topic that likely won’t see
it’s way into print, but helps
manage content.
Title samples

Ours has those elements, and it’s in the
map!
39

Elements used in most topic types
 paragraph
 table
 body related
 body
 conbody
 refbody
 taskbody
 Most body elements
contain a mix of common
things:
 section and example
 xref and related-links
 list related (ul, ol, and li)
 figure and image
 paragraph and title
40

7. Task is core to what user do
41
 In almost every situation people turn to
docs because they are doing things
 They discover a problem and need to look up
docs
 Highly unlikely people read about what to do
when the engine light comes on unless/until
the engine light comes on
 No one reads how to Create a Concept in
DITA unless they need to create concepts. In
DITA.
 An answer to how that tells the user just
what to do and the order in which to do it
 Step-by-step instructions that enables a
user to actually do something

Select where to add a task (in the map)
42
1

Let’s add it to the map automatically
43

Title is “Create a <concept>”, and add
shortdesc
44

Insert a <shortdesc> for the task
45
Type this: Introduce your
audience to an idea
before you make them
do things.
1
2

+You as the author, –<taskbody>, –<related-links>
46
1
2

Save and close the “non-map” content
47

Tasks also contain very specific elements
48
 task related elements
o prereq (before you begin)
o context (concise reason/benefit)
o steps (detailed below)
o result (net result of the entire task)
o example (specific example of the task)
o postreq (once done, additional “must to” items)
 steps related elements
o steps and steps-unordered, containing one or more
step
o cmd (specific instruction, call to action)
o info (additional content to help user perform the step)
o stepresult (specific result of JUST this step, not the task)
o tutorialinfo (content to help when working in a guided way)
o substeps (one level only, just as needed... Too many? Make a
new task!)

How about content contributed by SMEs
 Technical communicators
 Good with learning tools
 Work with many outputs
 Familiar with templates
 Comfortable in Word and
FrameMaker worlds
 Like to learn, dive in,
options
 Good candidates for work
in DITA and FrameMaker
 SMEs
 Quick contributors
 Not interested in all
outputs
 Simpler interface
 Passing familiarity with
Word and styles/tags
 Let them focus on their job
 Good candidates for an
easy, simplified DITA
workflow
49

8. References get to facts and details
 The tech stuff you look
up when you know the
big picture (concept) and
the procedure (task), but
you don’t recall specific
details
 Tables, lists, alphabetical
 Users should be able to
scan quickly and find
information
 Often technical or
background information
50

Remember the SMEs? How can we help
them?
51

This is how easy it SHOULD be for contributors
52

Let’s enter text under the <concept> title
53
Type: An idea, a quick
overview of something we
are documenting.

Add a bit more text in the reference
54
Type: Clear step-by-step
instructions. Only the call to
action, no conceptual or
reference information.

Several pre-defined elements exist
55
 Toolbars allow specific elements to be added
 Icons can be customized
 Knowing structure isn’t required
 It helps, and in many cases the technical communications
team should know it
 But now a SME can create DITA valid content
 Even new task/concept/reference content can be
built

DITA will NOT allow <section> if in a <title>
56

Simplified XML follows rules, its own way
57

Add <title> and <para>
58
Title: <reference> element
Para: Technical details,
tables, lookup info.

When SMEs are done, content returns to authors
59
 Toggle back to WYSIWYG (from pencil icon to sheet)
 Review the reference
 In some cases there may be cleanup
 Sure beats copy/paste and manual cleanup though
 Save and close the file

BTW, tasks and concepts are also
supported!
60

9. Publish content
 Native FrameMaker
 Support is included
 Run it by selecting File >
Publish
 Customize it using
 A visual interface
61
 DITA OT
 Support is included
 DITA > Generate DITA OT
Output
 Customize it using
 Scripts
 Developers
 Code
 Debugging

Publish with native FrameMaker
62

After a bit of wizardry
63

And to customize this output
64

From a map, DITA > Generate DITA OT
Output
65
1
2
3
4

Outputs supported in the OT include…
66

Some stuff happens, and the OT delivers to a
folder
67

Standard help content, right from DITA
68

Tasks, reference, all converted
69

And to customize the OT output
 Search (thanks Google!)
 To customize <codeblock>
to change the font color
and background color
 Figure out which attributes
to change.
 A full-text search for
"codeblock“ yields a few
results, one of which is
fo/xsl/pr-domain.xsl
 The template is found on
line 46: <xsl:template
match="*[contains(@class
,' pr-d/codeblock ')]">.
 The template shows us
we need to modify the
"codeblock" attribute set
on line 48: <fo:block
xsl:use-attribute-
sets="codeblock"
id="{@id}">
 The "codeblock" attribute
set is also in
fo/cfg/fo/attrs/pr-domain-
attr.xsl on line 41:
<xsl:attribute-set
name="codeblock">
 The next step is to
customize this attribute
set
70

Then we continue to customize it
 Copy
fo/Customization/fo/attrs/
custom.xsl.orig to custom.xsl
 Copy the codeblock attribute
set to the new XSL
 Find the code for the
background color and font
color so we can specify these
attributes
 The resulting code:
 <xsl:attribute-
set name="codeblock">
 <xsl:attribute name="backgrou
nd-
color">#ff0000</xsl:attribute>
 <xsl:attribute name="color">#ff
ffff</xsl:attribute>
 </xsl:attribute-set>
 Then tell the plugin to use the
customizations
 Copy /fo/Customization/
catalog.xml.orig to
catalog.xml
 Open the copied file and edit
the 6th row to uncomment the
code from:
 
 to:
 <uri
name="cfg:fo/xsl/custom.xsl"
uri="fo/xsl/custom.xsl">
 Save the file
 See. It’s easy to write code.
71

10: Reorg and republish
72

And, by the way File > Save Ditamap As >
...
73

You can create FrameMaker content from
DITA
74

If you want, use a simple form to do so
75

Your takeaway exercises
 With DITA content
 Use the map and open
files
 Add some more content to
the tasks, ensuring they
are valid (just take baby
steps)
 Add a <step> or two
 Save the files
 Publish and review
 Publishing FrameMaker
 Experiment with settings
 Create different outputs
 Test the format options
 Open content on different
devices
76

Summing up the discussion,
and options to continue it.
@aschwanden4stc 15:11
77
Conclusion and contact

In closing, we covered:
78
1. Setup of FrameMaker and create a bit of sample
content
2. Overview of DITA in a single slide
3. Intro to all core topic types and elements
4. Behind the scenes (attributes)
5. Map
6. Concept
7. Task
8. Reference
9. Publish
10. Update/Publish again!

Considering DITA?
79
 This was under an hour... It isn’t enough to get you
going
 But it provided ideas to think about
 Questions you should explore
 Do you even need DITA?
 If so, what about the content you have?
 Does it need to be cleaned up, re-written, converted?
 How do you get your templates into the DITA world?
 What about training, support, and potential content
management?
 The next slide is a great way to start that exploration


Thank you for your attention
80
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwanden
@publishsmarter (also
aschwanden4stc)
www.publishingsmarter.com

XML authoring simplified for one and all: Writers UA

Recomendados

Recomendados

Mais conteúdo relacionado

Destaque

Destaque (16)

Semelhante a XML authoring simplified for one and all: Writers UA

Semelhante a XML authoring simplified for one and all: Writers UA (20)

Mais de Publishing Smarter

Mais de Publishing Smarter (20)

Último

Último (20)

XML authoring simplified for one and all: Writers UA