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

April 20161

Stan Doherty, Ph.D.Stan@ModularWriting.com

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 establish connections between silos?

9

TECHPUBS

SUPPORT

ENGINEERING

UXD

MKT/PM

TRAINING

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

15

TECHPUBS

SUPPORT

UXD

MKT/PM

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.

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.

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

Map that hierarchy into a shared format (Excel)

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

Copy that markup into a subjectScheme map . . .

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

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

Add that subjectScheme map to your root map . . .

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

32

Convert UXD personas into DITA topics . . .

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"

34

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

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>

36

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

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

39

Become familiar with MKT/PM modelng tools . . .

40

Export that mindmap (hierarchy) to Excel . . .

41

Add Excel formulas for key definition markup . . .

subjectScheme markup key definition markup

42

Add Excel formulas for key definition markup . . .

XML topic <prolog> markup

HTML <head> output

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.