getting to first base: managing cross-organizational content with basic metadata
TRANSCRIPT
Getting to First Base: Managing Cross‐Organizational Content With Basic Metadata
April 20161
Stan Doherty, [email protected]
About the speaker . . .
2
Chequered past
Sordid present
Suspect future
• Music -- Top 40, heavy metal rock, wedding singer• Degrees – theology, linguistics, forensic bibliography (Elizabethan)• College – taught English literature, freshman comp, and tech writing• Trained – Lotus Development Corporation• Worked – PTC, Sun Microsystems, Verivue, Akamai Technologies
• Manager – SimpliVity Corporation (IT hyperconvergence startup)• Voting member – OASIS DITA Technical Committee• Secretary – OASIS DITA Adoption Technical Committee• Sketchy member – STC New England
• Mentor• Teacher – inner city• Grandfather• Writer
Here's the pitch . . .
3
Many of the DITA features that we exploit to make our technical publications pipeline more efficient can also serve as information modeling tools.
Here's the pitch . . .
4
Many of the DITA features that we exploit to make our technical publications pipeline more efficient can also serve as information modeling tools.
We and our peer content development organizations work in silos when it comes to delivering different types of publications and services – but – we tend to share a significant number of assumptions about our customers, products, and use cases.
Here's the pitch . . .
5
Many of the DITA features that we exploit to make our technical publications pipeline more efficient can also serve as information modeling tools.
We and our peer content development organizations work in silos when it comes to delivering different types of publications and services – but – we tend to share a significant number of assumptions about our customers, products, and use cases.
Those shared assumptions are metadata structures. We can model them in DITA. We can share them across multiple non‐DITA tools. We can demonstrate how these assumptions play out in multiple what‐if scenarios.
Here's the pitch . . .
6
Many of the DITA features that we exploit to make our technical publications pipeline more efficient can also serve as information modeling tools.
We and our peer content development organizations work in silos when it comes to delivering different types of publications and services – but – we tend to share a significant number of assumptions about our customers, products, and use cases.
Those shared assumptions are metadata structures. We can model them in DITA. We can share them across multiple non‐DITA tools. We can demonstrate how these assumptions play out in multiple what‐if scenarios.
The goal . . .
. . . IS NOT to develop production‐ready pipelines across organizations . . .
. . . IS to jumpstart discussions across your organization and to use DITA to profilethe opportunities and obstacles for eventual shared metadata solutions
What features and technologies do we exploit?
7
DITA features Technologies01. DITA‐compliant editor02. DITA Open Toolkit03. XQuery editor04. DITA‐compliant CCMS05. Schematron06. Scalable Vector Graphics07. Lightweight DITA (Markdown)08. DITA4Publishers09. Mind mapping editor10. Wireframe editor11. Spreadsheet
01. Inheritance (XML, processors)02. Generalization (XML, processors)03. Modular authoring (topic, maps)04. Information typing (topic types, domains)05. Content reuse (polymorphism)06. Semantic markup (OOTB, customized)07. Metadata: controlled values for attributes08. Metadata: taxonomies09. Metadata: classifications, ontologies10. Extensibility (info types, domains)11. Key‐based referencing12. Unicode and localization support13. Content filtering (conditional assembly)14. Content flagging (conditional styling)15. Content/style isolation16. Topic encapsulation 17. Content management integration
Which features and technologies support modeling?
8
DITA features Technologies01. DITA‐compliant editor02. DITA Open Toolkit03. XQuery editor04. DITA‐compliant CCMS05. Schematron06. Scalable Vector Graphics07. Lightweight DITA (Markdown)08. DITA4Publishers09. Mind mapping editor10. Wireframe editor11. Spreadsheet
01. Inheritance (XML, processors)02. Generalization (XML, processors)03. Modular authoring (topic, maps)04. Information typing (topic types, domains)05. Content reuse (polymorphism)06. Semantic markup (OOTB, customized)07. Metadata: controlled values for attributes08. Metadata: taxonomies09. Metadata: classifications, ontologies10. Extensibility (info types, domains)11. Key‐based referencing12. Unicode and localization support13. Content filtering (conditional assembly)14. Content flagging (conditional styling)15. Content/style isolation16. Topic encapsulation 17. Content management integration
How do we build connections between silos?
10
TECHPUBS
SUPPORT
ENGINEERING
UXD
MKT/PM
TRAINING
• Different terminology• Different authoring tools• Different modeling tools• Different priorities• Different target audiences• Different schedules• Different cultures
CHALLENGES
Can we do better than "throwing it over the wall"???
11
TECHPUBS
SUPPORT
ENGINEERING
UXD
MKT/PM
TRAINING
CONTENT
How can we segment the problem?
12
TECHPUBS
SUPPORT
ENGINEERING
UXD
MKT/PM
TRAINING
IDENTIFY TYPES OF CONNECTIONS
CONTENT
METADATA
Data Plane
Control Plane
What information?How delivered?How access it?
What audience?What subjects?What navigation?
How can we segment the problem?
13
TECHPUBS
SUPPORT
ENGINEERING
UXD
MKT/PM
TRAINING
• Unidirectional
• Duplex (bidirectional)
IDENTIFY DIRECTIONALITYFOR CONNECTIONS
Pick your battles . . .
14
TECHPUBS
SUPPORT
ENGINEERING
UXD
MKT/PM
TRAINING
CONTENT
CONTENT
METADATA
Data Plane
Control Plane
LIGHTWEIGHT DITA- Markdown (MDITA)- HTML5 (HDITA)- MS Word (WDITA)
DITA METADATA- Keys- Controlled vocabulary- Filtering/Flagging- Taxonomies
Identify one issue to address with each peer group . . .
16
TECHPUBS
SUPPORT
PROBLEMWe use different terminologyfor the same task content, sowe can't audit one another'srepositories.
Identify one issue to address with each peer group . . .
17
TECHPUBS
SUPPORT
PROBLEMWe use different terminologyfor the same task content, sowe can't audit one another'srepositories.
SOLUTIONDevelop a shared, controlled vocabulary for task-orientedcontent.
Use DITA to model and testit.
Copy that markup into a subjectScheme map . . .
Specifies that only the abovevalues be available for the @platform attribute.
Add to each <title> a controlled value for "action" (@otherprops) and "security object" (@platform) . . .
Add to each <title> a controlled value for "action" (@otherprops) and "security object" (@platform) . . .
Once action-object metadata is happy in DITA, implement it in MindTouch or SalesForce . . .
SUPPORT – KBAs with metadata
TECH PUBS - topics with metadata<topic otherprops="create" platform="backup policy">. . .<topic otherprops="copy" platform="backup policy">. . .<topic otherprops="delete" platform="backup policy">. . .<topic otherprops="edit" platform="backup policy">. . .<topic otherprops="deploy" platform="login manager">. . .<topic otherprops="view" platform="backup policy">
Once action-object metadata is happy in DITA, implement it in MindTouch or SalesForce . . .
SUPPORT – KBAs with metadata
TECH PUBS - topics with metadata<topic otherprops="create" platform="backup policy">. . .<topic otherprops="copy" platform="backup policy">. . .<topic otherprops="delete" platform="backup policy">. . .<topic otherprops="edit" platform="backup policy">. . .<topic otherprops="deploy" platform="login manager">. . .<topic otherprops="view" platform="backup policy">
XQuery
ResultSet
ResultSet
Any group can query either repo with the controlled vocabulary . . .
SUPPORT – KBAs with metadata
TECH PUBS - topics with metadata<topic otherprops="create" platform="backup policy">. . .<topic otherprops="copy" platform="backup policy">. . .<topic otherprops="delete" platform="backup policy">. . .<topic otherprops="edit" platform="backup policy">. . .<topic otherprops="deploy" platform="login manager">. . .<topic otherprops="view" platform="backup policy">
XQuery
ResultSet
ResultSet
If you are able to add a specialized element . . .
<svt-task-model
svt-action="value" cable | create | deploy | . . .
svt-object="value" node | vm | backup | . . .
svt-context="value" cli | gui | rest | setup | . . .
svt-comments="value"/> comments
29
TECHPUBS
UXD
PROBLEMWe model audience-specificinformation differently. UXDuses formal personas. We handle audiences informally.
Identify one issue to address with each peer group . . .
30
TECHPUBS
UXD
PROBLEMWe use different terminologyfor the same task content, sowe can't audit one another'srepositories.
SOLUTIONDevelop shared personnaswith shared metadata. Tag some sample content withmetadata and experimentwith filtering/flagging it.
Identify one issue to address with each peer group . . .
31
Re-implement UXD persona template in DITA . . .
1. Persona group2. Name3. Job title(s)4. Job responsibilities5. Demographics:
- age- education- ethnicity- family status
6. Goals7. Tasks8. Environment
- physical- social- technological
9. Focus - what matters most
10. Visuals
UXD Template
33
Develop some metadata tags for each persona . . .
Objects relevant for this persona . . . get this @rev attribute value . . .
Security Administration Manager (Kyle) @rev="persona-admin-manager"
Security Administration Architect (Leslie) @rev="persona-admin-architect"
Security Administration Technician (Bob) @rev="persona-admin-technician"
35
Outline some topics in DITA and tag for persona . . .
<p><b>Chapter 2: Overview of security features</b></p>
<p rev="persona_security-admin-manager"><xref href="security-arch.dita">About the security architecture</xref></p>
<p rev="persona_security-admin-tech"><xref href="sec-comp-1.dita">Security component-1</xref></p>
<p rev="persona_security-admin-tech"><xref href="sec-comp-2.dita">Security component-2</xref></p>
<p rev="persona_security-admin-tech"><xref href="sec-comp-3.dita">Security component-3</xref></p>
<p rev="persona_security-admin-architect"><xref href="sec-install-prereq.dita">Reference: security installation pre-requisites</xref></p>
<p rev="persona_security-admin-architect"><xref href="sec-network-prereq.dita">Reference: network pre-requisites</xref></p>
37
TECHPUBS
MKT/PM
PROBLEMWe visualize productdesign and feature evolutiondifferently. Marketing tendsto want one big map; we like outlines and multiple deliverables.
Identify one issue to address with each peer group . . .
38
TECHPUBS
MKT/PM
PROBLEMWe use different terminologyfor the same task content, sowe can't audit one another'srepositories.
SOLUTIONDevelop a shared hierarchyof product feature areas.
Model the hierarchy in DITAsubjectScheme maps and MindMapping software.
Identify one issue to address with each peer group . . .
43
Conclusions: Give it a try . . . stay in touch . . .Many of the DITA features that we exploit to make our technical publications pipeline more efficient can also serve as information modeling tools.
We and our peer content development organizations work in silos when it comes todelivering different types of publications and services – but – we tend to share asignificant number of assumptions about our customers, products, and use cases.
Those shared assumptions are metadata structures. We can model them in DITA. We can share them across multiple non‐DITA tools. We can demonstrate how these assumptions play out in multiple what‐if scenarios.