xml authoring simplified for one and all: writers ua

21:08

Bernard Aschwanden

www.publishingsmarter.com

bernard@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)

bernard@publishingsmarter.com

www.linkedin.com/in/bernardaschwanden

@publishsmarter (also aschwanden4stc)

www.publishingsmarter.com