Embed Size (px)
Citation preview
21:08
Bernard Aschwanden
www.publishingsmarter.com
XML Authoring SimplifiedFor One and All
1
@aschwanden4stc
21:08
Housekeeping
@aschwanden4stc
2
Thanks to Adobe and Joe for setting up this eventIn under 10 ideas (was slides, but I don’t want you
to write)1. Setup of FrameMaker and create a bit of sample content2. Overview of DITA in a single slide3. Intro to all core topic types and elements4. Behind the scenes (attributes)5. Map6. Concept7. Task8. Reference9. Publish10. Update/Publish again!
21:08@aschwanden4stc
3
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
21:08
Many options exist, so let’s get onto the same page (so to speak)
@aschwanden4stc
4
Setting up the software
21:08@aschwanden4stc
5
1. Let’s standardize things: Edit > Preferences
1
2
3
21:08
Enable Simplified XML (more on that later)
@aschwanden4stc
6
1
2
3
21:08
If needed, relaunch, then File > New > XML
@aschwanden4stc
7
12
3
21:08
By default you see this (or similar)
@aschwanden4stc
8
21:08
Change to a structured author mode
@aschwanden4stc
9 1
2
21:08
Structure View: Hierarchy of content
@aschwanden4stc
10
21:08
Element Catalog: Contextual list
@aschwanden4stc
11
21:08
Setup of a custom workspace (one time)
@aschwanden4stc
12
1
2
21:08
Collapse by double-clicking
@aschwanden4stc
13
1
21:08
Save your own workspace
@aschwanden4stc
14 1
23
4
21:08
Remove <related-links>
@aschwanden4stc
15
1
21:08
Add a title
@aschwanden4stc
16
1
21:08
Content in doc and in Structure View
@aschwanden4stc
17
21:08
Inline: View > Element Boundaries (as Tags)
@aschwanden4stc
18
21:08
Add content in tags, select/delete related-links
@aschwanden4stc
19
21:08
View > Hide Element Boundaries
@aschwanden4stc
20
21:08
Save the file (anywhere, but make a folder)
@aschwanden4stc
21
21:08@aschwanden4stc
22
2. Purpose of DITA
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!
21:08
2: Overview of DITA in a single slide
@aschwanden4stc
23
Darwin Information Typing ArchitectureDITA is about Topic, Maps, SpecializationsSome specializations include
concept, reference, task,glossary (topic based)
bookmap (map based) domains (software, programming)
DITA 1.2 and 1.3 introduce morebased on the standard core topics
DITA Information TypesTopic–Concept–Task–Reference
21:08
3. Intro to core topic types and elements
@aschwanden4stc
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
21:08
4. Behind the scenes are attributes
@aschwanden4stc
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
21:08
4b. You likely already know about attributes
@aschwanden4stc
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>
21:08
5. Use maps to organize info
@aschwanden4stc
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
21:08
5. Let’s build a New <map> in FrameMaker
@aschwanden4stc
281
2
21:08
File > Save Ditamap As... (m_DITA_and_FrameMaker)
@aschwanden4stc
29
21:08
Different views based on preferences/functions
@aschwanden4stc
30
21:08
Change text? Double click snippets to select all
@aschwanden4stc
31
21:08
When content is selected, just type to edit
@aschwanden4stc
32
21:08
Let’s add the concept to the book
@aschwanden4stc
33
21:08
Add a <topicref> (a topic reference)
@aschwanden4stc
34
21:08
Double-click a file that already exists
@aschwanden4stc
35
12
21:08
So far, pretty simple, but a bit unimpressive
@aschwanden4stc
36
21:08
6. Concept explains ideas
@aschwanden4stc
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
21:08
Key elements when getting started
@aschwanden4stc
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
21:08
Ours has those elements, and it’s in the map!
@aschwanden4stc
39
21:08
Elements used in most topic types
@aschwanden4stc
paragraphtablebody 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
21:08
7. Task is core to what user do
@aschwanden4stc
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
21:08
Select where to add a task (in the map)
@aschwanden4stc
42
1
21:08
Let’s add it to the map automatically
@aschwanden4stc
43
21:08
Title is “Create a <concept>”, and add shortdesc
@aschwanden4stc
44
21:08
Insert a <shortdesc> for the task
@aschwanden4stc
45
Type this: Introduce your audience to an idea before you make them do things.
12
21:08
+You as the author, –<taskbody>, –<related-links>
@aschwanden4stc
46
1
2
21:08
Save and close the “non-map” content
@aschwanden4stc
47
21:08
Tasks also contain very specific elements
@aschwanden4stc
48
task related elementso 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 elementso steps and steps-unordered, containing one or more
stepo 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!)
21:08
How about content contributed by SMEs
@aschwanden4stc
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
21:08
8. References get to facts and details
@aschwanden4stc
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, alphabeticalUsers should be able to
scan quickly and find information
Often technical or background information
50
21:08
Remember the SMEs? How can we help them?
@aschwanden4stc
51
21:08
This is how easy it SHOULD be for contributors
@aschwanden4stc
52
21:08
Let’s enter text under the <concept> title
@aschwanden4stc
53
Type: An idea, a quick overview of something we are documenting.
21:08
Add a bit more text in the reference
@aschwanden4stc
54
Type: Clear step-by-step instructions. Only the call to action, no conceptual or reference information.
21:08
Several pre-defined elements exist
@aschwanden4stc
55
Toolbars allow specific elements to be addedIcons can be customizedKnowing 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 contentEven new task/concept/reference content can
be built
21:08
DITA will NOT allow <section> if in a <title>
@aschwanden4stc
56
21:08
Simplified XML follows rules, its own way
@aschwanden4stc
57
21:08
Add <title> and <para>
@aschwanden4stc
58
Title: <reference> element
Para: Technical details, tables, lookup info.
21:08
When SMEs are done, content returns to authors
@aschwanden4stc
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
21:08
BTW, tasks and concepts are also supported!
@aschwanden4stc
60
21:08
9. Publish content
@aschwanden4stc
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
21:08
Publish with native FrameMaker
@aschwanden4stc
62
21:08
After a bit of wizardry
@aschwanden4stc
63
21:08
And to customize this output
@aschwanden4stc
64
21:08
From a map, DITA > Generate DITA OT Output
@aschwanden4stc
65
1
2
3
4
21:08
Outputs supported in the OT include…
@aschwanden4stc
66
21:08
Some stuff happens, and the OT delivers to a folder
@aschwanden4stc
67
21:08
Standard help content, right from DITA
@aschwanden4stc
68
21:08
Tasks, reference, all converted
@aschwanden4stc
69
21:08
And to customize the OT output
@aschwanden4stc
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
21:08
Then we continue to customize it
@aschwanden4stc
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="backgroun
d-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: <!--uri
name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->
to: <uri
name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl">
Save the file See. It’s easy to write code.
71
21:08
10: Reorg and republish
@aschwanden4stc
72
21:08
And, by the way File > Save Ditamap As > ...
@aschwanden4stc
73
21:08
You can create FrameMaker content from DITA
@aschwanden4stc
74
21:08
If you want, use a simple form to do so
@aschwanden4stc
75
21:08
Your takeaway exercises
@aschwanden4stc
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
@aschwanden4stc 21:08
77
Summing up the discussion,and options to continue it.
Conclusion and contact
21:08
In closing, we covered:
@aschwanden4stc
78
1. Setup of FrameMaker and create a bit of sample content
2. Overview of DITA in a single slide3. Intro to all core topic types and elements4. Behind the scenes (attributes)5. Map6. Concept7. Task8. Reference9. Publish10.Update/Publish again!
21:08
Considering DITA?
@aschwanden4stc
79
This was under an hour... It isn’t enough to get you going
But it provided ideas to think aboutQuestions 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
21:08@aschwanden4stc
80
Thank you for your attention
905 833 8448 (Eastern Time)
www.linkedin.com/in/bernardaschwanden
@publishsmarter (also aschwanden4stc)
www.publishingsmarter.com
