Top Banner
Getting to First Base: Managing CrossOrganizational Content With Basic Metadata April 2016 1 Stan Doherty, Ph.D. [email protected]
44

Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Apr 10, 2017

Download

Technology

Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Getting to First Base: Managing Cross‐Organizational Content With Basic Metadata

April 20161

Stan Doherty, [email protected]

Page 2: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 3: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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. 

Page 4: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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. 

Page 5: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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. 

Page 6: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 7: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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 

Page 8: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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 

Page 9: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

How do we establish connections between silos?

9

TECHPUBS

SUPPORT

ENGINEERING

UXD

MKT/PM

TRAINING

Page 10: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 11: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Can we do better than "throwing it over the wall"???

11

TECHPUBS

SUPPORT

ENGINEERING

UXD

MKT/PM

TRAINING

CONTENT

Page 12: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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?

Page 13: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

How can we segment the problem?

13

TECHPUBS

SUPPORT

ENGINEERING

UXD

MKT/PM

TRAINING

• Unidirectional

• Duplex (bidirectional)

IDENTIFY DIRECTIONALITYFOR CONNECTIONS

Page 14: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 15: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Identify one issue to address with each peer group . . .

15

TECHPUBS

SUPPORT

UXD

MKT/PM

METADATA

Page 16: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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.

Page 17: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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.

Page 18: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

If you can, start from a shared taxonomy . . .

Page 19: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Map that hierarchy into a shared format (Excel)

Page 20: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Identify key objects in shared tasks ... with Excel formulas to generate DITA markup . . .

Page 21: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Copy that markup into a subjectScheme map . . .

Specifies that only the abovevalues be available for the @platform attribute.

Page 22: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

List key "actions" in Excel for shared tasks . . . add to the subjectScheme map . . .

Page 23: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Add that subjectScheme map to your root map . . .

Page 24: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Add to each <title> a controlled value for "action" (@otherprops) and "security object" (@platform) . . .

Page 25: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

Add to each <title> a controlled value for "action" (@otherprops) and "security object" (@platform) . . .

Page 26: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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">

Page 27: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 28: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 29: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

29

TECHPUBS

UXD

PROBLEMWe model audience-specificinformation differently. UXDuses formal personas. We handle audiences informally.

Identify one issue to address with each peer group . . .

Page 30: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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 . . .

Page 31: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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

Page 32: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

32

Convert UXD personas into DITA topics . . .

Page 33: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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"

Page 34: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

34

Outline some topics in DITA and tag for persona . . .

Page 35: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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>

Page 36: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

36

Use DITA flagging to differentiate persona content in output . . .

Page 37: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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 . . .

Page 38: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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 . . .

Page 39: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

39

Become familiar with MKT/PM modelng tools . . .

Page 40: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

40

Export that mindmap (hierarchy) to Excel . . .

Page 41: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

41

Add Excel formulas for key definition markup . . .

subjectScheme markup key definition markup

Page 42: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

42

Add Excel formulas for key definition markup . . .

XML topic <prolog> markup

HTML <head> output

Page 43: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata

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. 

Page 44: Getting to First Base: Managing Cross-Organizational Content with Basic Metadata