xml for humans: non-geek discussion of a geek-chic topic

60
Getting to know a bit about XML without having to dive into all the tech talk Bernard Aschwanden www.publishingsmarter.com for a print version, please email [email protected] XML for Humans: Non- geek Discussion of a Geek-chic Topic 06:52 1 @publishsmarter

Upload: publishing-smarter

Post on 08-May-2015

216 views

Category:

Technology


0 download

DESCRIPTION

This session, presented at the Editors Conference in Toronto, on June 8, 2014, introduces you to the basics of XML, explaining what it is, how it is used, and why it benefits people who write and edit. While THEY may love to work with code, the goal was to put as much of this into plain language for US as possible. I think it succeeded. Participants could learn how clear and concise content can be created (and managed) in an XML workflow. At the end of the session they had enough knowledge to speak about XML with confidence. During the session detailed slides were presented and discussed. A packed room attended and participated (the session featured a lot of great questions and answers) over the span of an hour.

TRANSCRIPT

Page 1: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

Gett ing to know a bi t about XML without having to d ive into a l l the tech ta lk

Bernard Aschwanden

www.publ ish ingsmarter.com

f o r a p r i n t v e r s i o n , p l e a s e em a i lb e rna rd @p ub l i s h i ng s m a r t e r. co m

XML for Humans: Non-geek Discussion of a Geek-chic

Topic1

@publishsmarter

Page 2: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28@publishsmarter

2

About this session

Intro to the basicsDefine what XML isHow it is usedWhy it benefits people who write and editLearn how clear and concise content can be

created (and managed) in an XML workflowKnow the difference between an XML editor

and an editor (or writer, or whomever) who knows XML

Speak about XML with confidence

Page 3: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

Rule 1: Know your audience

@publishsmarter

3

Here because nothing else on the agenda looked good?

Here because the topic is something you Have a basic interest in? Have a lot of interest in? Love more than almost anything else on earth?

Already generally familiar with this topic?Comfortable with HTML (even <img

scr=“logo.gif” />)

Page 4: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

Housekeeping and note taking

@publishsmarter

4

Not all slides or topics are equally weighted

Use some, discard othersSlides speed varies

(reference)Questions? Ask along the

way!

I’d love to claim errors/typos is on purpose… they isn’t, ain’t, and weren’t never; however, I’ll fix ‘em as I can…

Page 5: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

About your speaker

@publishsmarter

5

Publishing Smarter: President

Content strategist, publishing technologies expert, author, and geek-enough

Certified Technical Trainer DITA Content management Topic-based writing

Society for Technical Communications Vice President STC Associate Fellow

Page 6: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

Services

@publishsmarter

6

We help clients: Create great content Manage content as an asset Deliver content the right

way Socialize the message Listen to the consumer Improve experiences by

helping Create great content Manage content as an asset Deliver content the right way …

By helping clients:

Page 7: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

Standard disclaimer

@publishsmarter

7

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)

Page 8: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:28

I wi l l attempt this in under 150 sl ides

@publishsmarter

8

Problems with content creators

Page 9: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Slide 1/149... They like to create content

@publishsmarter

9

They create a lot, often without following style guides They like to create as they see fit They create in any order They create based on all that they know

They may truly believe that template styles are for show They format on the fly They don’t use the right formats They DO manually apply formats and ignore styles

Page 10: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Documentation issues (where XML may help)

@publishsmarter

10

Documentation costs money Researching and reviewing content Software tools and training Development of multiple outputs Customizing materials for clients/partners Translation of content

XML can save money AND generate revenue There is upfront time/effort/cost/etc. ROI has been proven Let’s go explore XML

Page 11: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

eXtensible Markup Language

@publishsmarter

11

Basics of XML

Page 12: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

12

Defining XML

@publishsmarter

Wikipedia: Extensible Markup Language (XML) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable

Oracle: XML is a text-based markup language that is fast becoming the standard for data interchange on the web

w3schools: XML does not do anything; it was created to structure, store, and transport information

Page 13: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

The purpose of XML for documentation

@publishsmarter

13

Allows for structured writingProvides software tool independenceSeparates format and content

With a standard like DITA, it goes even further(another full presentation, but I will touch on this...)

Page 14: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

14

XML supports structured writing

@publishsmarter

Structure implies a set of defined rules (law, math, engineering, grammar)

Writing implies the creation of content

Structured content consistently follows the rules

A good foundation results in a happy home

Page 15: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Improve quality, reduce costs, increase profit

@publishsmarter

15

Long term benefits offset short term costsDocs can be created, modified, versioned,

stored, published, translated, customized, distributed, etc. easily

Content can be programmatically modified or assembled

Some tasks can be automated

Heck, you may already by ‘structured’ but not in XML

Or you may be using XML, and not even know it yet

Page 16: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Some (relatively) basic XML code

@publishsmarter

16

Exploring the code

Page 17: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

What does it look like?

@publishsmarter

17

Looks a lot like HTML (or it can) <p>This sample <i>ain’t</i> perfect; just basic

ideas.</p>

It’s a <p>aragraph, and has some <i>talic content in it.The </i>talic content ends, then the </p>aragraph ends.

<img src=“logo.gif” height=“100” width=“50” />

Let’s dissect an element

Part Function

img Name of the element

src Name of an attribute

logo.gif Value of the attribute

Page 18: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

What does it look like?

@publishsmarter

18

Looks a lot like HTML (or it can) <p>This sample <i>ain’t</i> perfect; just basic

ideas.</p>

It’s a <p>aragraph, and has some <i>talic content in it.The </i>talic content ends, then the </p>aragraph ends.

<img src=“logo.gif” height=“100” width=“50” />

Let’s dissect an element

Part Function

img Name of the element

src Name of an attribute

logo.gif Value of the attribute

Page 19: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

What does it look like?

@publishsmarter

19

Looks a lot like HTML (or it can) <p>This sample <i>ain’t</i> perfect; just basic

ideas.</p>

It’s a <p>aragraph, and has some <i>talic content in it.The </i>talic content ends, then the </p>aragraph ends.

<img src=“logo.gif” height=“100” width=“50” />

Let’s dissect an element

Part Function

img Name of the element

src Name of an attribute

logo.gif Value of the attribute

Page 20: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

What does it look like?

@publishsmarter

20

Looks a lot like HTML (or it can) <p>This sample <i>ain’t</i> perfect; just basic

ideas.</p>

It’s a <p>aragraph, and has some <i>talic content in it.The </i>talic content ends, then the </p>aragraph ends.

<img src=“logo.gif” height=“100” width=“50” />

Let’s dissect an element

Part Function

img Name of the element

src Name of an attribute

logo.gif Value of the attribute

Page 21: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

What does it look like?

@publishsmarter

21

Looks a lot like HTML (or it can) <p>This sample <i>ain’t</i> perfect; just basic

ideas.</p>

It’s a <p>aragraph, and has some <i>talic content in it.The </i>talic content ends, then the </p>aragraph ends.

<img src=“logo.gif” height=“100” width=“50” />

Let’s dissect an element

Part Function

img Name of the element

src Name of an attribute

logo.gif Value of the attribute

Page 22: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Some (sl ightly complex) basic XML code

@publishsmarter

22

Digging a bit deeper

Page 23: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

It can look a lot more complex though

@publishsmarter

23<?xml version="1.0" encoding="UTF-8" standalone="yes"?><p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"

xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"

xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"><p:cSld>

<p:spTree> <p:nvGrpSpPr> <p:cNvPr id="1" name=""/> <p:cNvGrpSpPr/> <p:nvPr/> </p:nvGrpSpPr> <p:sp> <p:nvSpPr> <p:cNvPr id="2" name="Title 1"/> <p:cNvSpPr> <a:spLocks noGrp="1"/> </p:cNvSpPr> <p:nvPr> <p:ph type="title"/> </p:nvPr> </p:nvSpPr> <p:spPr/> <p:txBody> <a:bodyPr/> <a:lstStyle/> <a:p> <a:r> <a:rPr lang="en-CA" smtClean="0"/> <a:t>It can look a LOT more complex though</a:t> </a:r> <a:endParaRPr lang="en-CA“ /> </a:p> </p:txBody>

This is actually part of the XML for the current slide with JUST the title in it

This is from the XML file that is behind the scenes in PowerPoint (and most MS Office products)

Technically, if you use Word, Excel, or PowerPoint, you use XML. Technically.

Page 24: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Looking at XML versions of MS Office

@publishsmarter

24

1. Take any *.docx, *.pptx, or *.xlsx and make a copy

Page 25: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Looking at XML versions of MS Office

@publishsmarter

25

1. Take any *.docx, *.pptx, or *.xlsx and make a copy

2. Rename it *.zip

Page 26: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Looking at XML versions of MS Office

@publishsmarter

26

1. Take any *.docx, *.pptx, or *.xlsx and make a copy

2. Rename it *.zip

3. Open it up and explore(in PowerPoint, start @ ppt)

Page 27: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Explore the slides folder

@publishsmarter

27

Page 28: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

XML View: The title of slide 1

@publishsmarter

28

<p:txBody><a:bodyPr/><a:lstStyle/><a:p> <a:r> <a:rPr lang="en-CA" />

<a:t>XML for Humans: Non-geek Discussion of a Geek-chic Topic</a:t> </a:r> <a:endParaRPr lang="en-CA"/></a:p></p:txBody>

Page 29: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

XML View: The body of slide 1

@publishsmarter

29

<p:txBody> <a:bodyPr/> <a:lstStyle/> <a:p> <a:r> <a:rPr lang="en-CA"/>

<a:t>Bernard Aschwanden</a:t> </a:r> </a:p> <a:p> <a:endParaRPr lang="en-CA"/> </a:p> <a:p> <a:r> <a:rPr lang="en-CA"/>

<a:t>www.publishingsmarter.com</a:t> </a:r> </a:p> <a:p> <a:endParaRPr lang="en-CA"/> </a:p> <a:p> <a:r> <a:rPr lang="en-CA"/>

<a:t>[email protected]</a:t> </a:r> <a:endParaRPr lang="en-CA"/> </a:p> </p:txBody>

Page 30: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Human usable XML might look moe like this

@publishsmarter

30

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []><task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser“> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody></task>

Page 31: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Reading it can be pretty simple (ignore code)

@publishsmarter

31

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []><task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser"> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody></task>

Page 32: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Structure has some human-friendly feel to it

@publishsmarter

32

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []><task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser"> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody></task>

Page 33: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

You can even understand the attributes

@publishsmarter

33

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []><task id="id_t_lighting_lvl"> <title>Adjust lighting levels</title> <shortdesc>Room or seat brightness can be individually configured.</shortdesc> <taskbody> <context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser"> For safety, admins can override preferences.</p><p audience="Administrator">You can override any personal preferences.</p></context> <steps> <step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step> <step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd> <info audience="Administrator"> <p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p> </info> </step> <step> <cmd>Tap the appropriate light level or configuration.</cmd> </step> </steps> </taskbody></task>

Page 34: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Remember that XML provides a division

@publishsmarter

34

Format Conten

t

Page 35: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

With XML you spend your time wisely

@publishsmarter

35

Page 36: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Content is manageable (size)

@publishsmarter

36

Format

Function

*.fm FrameMaker

*.txt Plain text

*.docx Word

*.xml Structure, store, transport

Page 37: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Content is manageable (CCMS)

@publishsmarter

37

Page 38: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Many editors (tools) support XML

@publishsmarter

38

Real world work with XML

Page 39: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Notepad. You can edit with Notepad. Woo. Hoo.

@publishsmarter

39

Page 40: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Code view if you want/need it

@publishsmarter

40

Page 41: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Code view is only one option

@publishsmarter

41

Page 42: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Across multiple tools

@publishsmarter

42

Page 43: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Mainstream tools offer a lot of support

@publishsmarter

43

Page 44: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

All the code is still there...

@publishsmarter

44

Page 45: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

XML makes it easier to focus on detai ls

@publishsmarter

45

Working with specific content

Page 46: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

You can choose to show JUST the EndUser

@publishsmarter

46

Page 47: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Show and hide based on attributes and values

@publishsmarter

47

Page 48: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Or choose just Administrator content

@publishsmarter

48

Page 49: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Display audience specific content

@publishsmarter

49

Page 50: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Net benefit of two topics, one source

@publishsmarter

50

Less editingFewer editsLess review timeQuicker approvalsFewer overall words to manage

Page 51: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Pull together what you need

@publishsmarter

51

Quick and easy to assemble

Page 52: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Linear writing versus topic-based (DITA)

@publishsmarter

52

Page 53: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

This means that you can...

@publishsmarter

53

Open a single instance of a topicEdit only what is relevant, and based on

specific contextIn DITA, for example:Attribute General purpose

audience Supports conditional processing for filtering or flagging.For example, EndUser or Administrator

importance

obsolete | deprecated | optional | default | low | normal | high | recommended | required | urgent

status new | changed | deleted | unchanged

translate yes | no

Page 54: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Many XML topics can come together

@publishsmarter

54

TO PIC

REFEREN CECO N CEPT

TASKTO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

TO PIC

REFEREN CECO N CEPT

TASK

Page 55: XML for Humans: Non-geek Discussion of a Geek-chic Topic

It is not output restrictive

Navigation Tools

Page 56: XML for Humans: Non-geek Discussion of a Geek-chic Topic

It is not device dependent

Navigation Tools

Page 57: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Summing up the discussion,and options to continue it.

@publishsmarter

57

Conclusion and contact

Page 58: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29@publishsmarter

58

About this session

Intro to the basicsDefine what XML isHow it is usedWhy it benefits people who write and editLearn how clear and concise content can be

created (and managed) in an XML workflowKnow the difference between an XML editor

and an editor who knows XMLSpeak about XML with confidence

Page 59: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Final request

@publishsmarter

59

Please suggest these slides to othersIf there are any problems with them, please

let me knowRemember my disclaimer at the beginning

Not all slides are equal: Use some, discard others In the interest of brevity I make some blanket

statements It’s not all 100% “the truth”, but I’ll stay close Purists may complain

And they are wrong! (except when they are right)

Page 60: XML for Humans: Non-geek Discussion of a Geek-chic Topic

22:29

Follow up contact information

@publishsmarter

60

905 833 8448 (Eastern Time)

[email protected]

www.linkedin.com/in/bernardaschwanden

@publishsmarter

www.publishingsmarter.com