xml for humans: non-geek discussion of a geek-chic topic
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
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
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
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” />)
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…
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
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:
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)
22:28
I wi l l attempt this in under 150 sl ides
@publishsmarter
8
Problems with content creators
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
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
22:29
eXtensible Markup Language
@publishsmarter
11
Basics of XML
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
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...)
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
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
22:29
Some (relatively) basic XML code
@publishsmarter
16
Exploring the code
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
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
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
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
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
22:29
Some (sl ightly complex) basic XML code
@publishsmarter
22
Digging a bit deeper
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.
22:29
Looking at XML versions of MS Office
@publishsmarter
24
1. Take any *.docx, *.pptx, or *.xlsx and make a copy
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
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)
22:29
Explore the slides folder
@publishsmarter
27
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>
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>
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>
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>
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>
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>
22:29
Remember that XML provides a division
@publishsmarter
34
Format Conten
t
22:29
With XML you spend your time wisely
@publishsmarter
35
22:29
Content is manageable (size)
@publishsmarter
36
Format
Function
*.fm FrameMaker
*.txt Plain text
*.docx Word
*.xml Structure, store, transport
22:29
Content is manageable (CCMS)
@publishsmarter
37
22:29
Many editors (tools) support XML
@publishsmarter
38
Real world work with XML
22:29
Notepad. You can edit with Notepad. Woo. Hoo.
@publishsmarter
39
22:29
Code view if you want/need it
@publishsmarter
40
22:29
Code view is only one option
@publishsmarter
41
22:29
Across multiple tools
@publishsmarter
42
22:29
Mainstream tools offer a lot of support
@publishsmarter
43
22:29
All the code is still there...
@publishsmarter
44
22:29
XML makes it easier to focus on detai ls
@publishsmarter
45
Working with specific content
22:29
You can choose to show JUST the EndUser
@publishsmarter
46
22:29
Show and hide based on attributes and values
@publishsmarter
47
22:29
Or choose just Administrator content
@publishsmarter
48
22:29
Display audience specific content
@publishsmarter
49
22:29
Net benefit of two topics, one source
@publishsmarter
50
Less editingFewer editsLess review timeQuicker approvalsFewer overall words to manage
22:29
Pull together what you need
@publishsmarter
51
Quick and easy to assemble
22:29
Linear writing versus topic-based (DITA)
@publishsmarter
52
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
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
It is not output restrictive
Navigation Tools
It is not device dependent
Navigation Tools
22:29
Summing up the discussion,and options to continue it.
@publishsmarter
57
Conclusion and contact
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
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)
22:29
Follow up contact information
@publishsmarter
60
905 833 8448 (Eastern Time)
www.linkedin.com/in/bernardaschwanden
@publishsmarter
www.publishingsmarter.com