How DITA got her groove back:

Going Mapless(a.k.a. Lessons from The School of Practical Experience)

Don DayLearning by Wrote

Information Development World 2015, San Jose, California 1

Don Day• Twitter: @donrday• Web site: http://learningbywrote.com• 25 years in Information Development at IBM• Founding Chair, OASIS DITA Technical Committee 2004-2013• Passion: DITA as Intelligent Content for the Web

• #MaplessDITA for Twitter karma

2

Motivations• To dispel some popular myths:• “DITA is mainly for Tech Comm”• “DITA is defined by Concept, Task, and Reference”• “DITA is too complex/has too many tags”• “DITA requires a CMS”

• To encourage DITA’s uptake in more roles:• Lightweight knowledge capture• Collections based on local metadata• Semantic single components (recipes, collectibles, terms)• Customization deferred from build time (preselection by author) to

search time (selection by reader)• Direct-to-Web publishing as Page One articles

• Based on explorations with ongoing expeDITA project

3

Perspectives on context:

4

Polynesian stick chart(a.k.a. wayfinder)• A Wayfinder represents the contexts that can influence your

content journey

• Not a map or guided tour of destinations• As in “Where to go”

• But knowledge about the options along your path• As in “Ways to go”

5

But where am I?

Image source: http://www.eurosail.ro/forum/viewtopic.php?f=30&t=387

6

Compass, sextant and chronometer• Sextant for latitude• Chronometer for longitude• Compass for direction

• Determines “Where am I”• My relationship to points of interest

7

Setting our context: What is context, anyway?

8

Per User Centered Design:

Context is everything.

We must ground our work in a rich understanding of the context of use, or else we run the risk of creating well meaning rubbish.Iain Barker, http://www.simplerisbetter.wordpress.com

9

Per Business Process:

Background, environment, framework, setting, or situation

surroundingan event or occurrence.

http://www.businessdictionary.com/definition/context.html

10

Dissecting the definition

“Background, environment, framework, setting, or situation

A context has unique characteristics or properties

surrounding Implies temporal and spatial cues (sequence, location)

an event or occurrence.”

Signifies a triggering condition (matching a rule)

11

In daily life:

• Context involves sensors providing data to a system for determining an action• Thermostats, toasters, flush valves (terminate activity

upon reaching a limit)• Responsive Web Design (reflow page designs based on

device queries)• Any profile-based activity (defining what interactions

you want to receive)

12

In DITA:• Context involves properties that can be acted upon by processing

filters (ditaval)

• These properties can be modified:• By map context (topicmeta property cascade)• By branch filtering (changing key resolution in different parts of the map)

• Elements with properties that match a rule can be:• Filtered (selectively exclude or include)• Flagged (selectively adorn stylistically)

• Conditional processing effectively removes some selection (ergo context) for users. This can lead to… 13

The “Fourth wall” dilemma

• Outtake from “The Boxtrolls”:

“I think it throws out notions of free will.”

The Boxtrolls: Time Lapse End Credits

14

Ways around the problem

By Jens Lelie, unsplash.com

15

Signs on each path:The Compile path• Map is the context

• Topic properties are derived and mutable

• Deliverables in multiple versions to anticipate multiple use cases

• We know this path…

The Grab-and-go path• Environment is the

context• Topic properties are

generally immutable

• Resources rendered according to RI, RP, RT

• But what’s down this one?16

Grab-and-Go scenarios• Microsites: content prepared specifically for one product or

service or user request• Specific car models or genres of music, movies, plays• Entertainment (often branded; cat videos OMG)• Calculators, comparators, configurators, troubleshooters• Gaming sites, collector sites, hobby sites (lore)• Consumer education and awareness of issues, candidates

• Long form reading (blogs, magazines, news)• Fan, tribute, meme sites • Emergency preparedness playbooks and how-to• Wikis for SME knowledge capture, agile team collaboration

17

Harnessing new contexts• A loosely coupled architecture:• Allows rich selection (greatest affordance of facets and content for

users)• Enables deep searchability (search is a way to pass live selection

filters to a set of content)• Applies context-modified views to the result (both map and topic)• (a.k.a. Adaptable Content)

• Resolve in the browser (XML is available for JavaScript logic)• Resolve on the server (optimize use of bandwidth, caching)• State machines watch for actionable signals.

• Wait… state what?18

You’ve seen them before!• A state machine uses inputs (context!) to determine when to

change states and call new behaviors• Conditional processing for DITA involves a state machine:

<prop att="product“ val="extendedprod“ action="exclude"/>

I.e., if the value of the current element’s product attribute is "extendedprod" then exclude the element.

• With mobile devices, contextual data includes geolocation, time, velocity, direction, image and biometric processing

• Or user profile, bookmarks, browse history, contact lists…• Or responses to a form

19

Net on State Machines• #MaplessDITA is very much about moving state-based

behaviors closer to the user’s encounter with the content

20

Topics have internal contexts• Direct properties (metadata in a prolog)• Creation date• Author• Status

• Indirect properties (ids or keywords that associate topic to other collections)• Category• Resourceid• Publisher, Series, Source, etc.

21

Topics have context by proxy• The domain of use may suggest context-dependent values• In a software lab, italics nearly always signify variables• At a semiconductor design facility, overlined terms (new in DITA 1.3) likewise

signify flags (on/off conditions)

• Artifacts of user curation: bookmark files, known prior reuse

• History of reuse--has it been historically organized by: • Length• Alphabet• Time• Category• Hierarchy

“Because you are at #IDW2015, you must be a content professional!”

22

Queries and parameters• A URL can be extended by• Additional parameter segments (‘/size/large/color/blue’)• Parameter queries (‘?size=large&color=blue’)• “Post” data from forms is another, less obvious, way to pass

query data to an application• The ? method is actually how many CMSs locate versioned

resources• In effect, URL parameters provide context that can apply to

stateful views of the resource

23

How to let a topic assert itself• Best practices• Fill in all appropriate metadata in prolog• If semantic markup is available, use it (<code> instead of <tt>)• Consider using indexing and keywords; these help improve search

even after publication• Use DITA’s searchtitle element to represent how search tools list

your topic when it shows up on search results. You want readers to see and pick out your topic from a sea of candidate hits.

• Select markup for what something is, not for how it appears *

*24

What then is Mapless DITA?• Topics• Contexts• Processing• A philosphy

25

Topics in Mapless DITA• A Topic does not need to rely on maps for their properties or

behaviors• Meaning that the topic can be used in map-based builds that

resolve properties• But the topic has no build-breaking dependencies on the map for

context• Many topics in current content repositories are already

compliant for this kind of use. • How:• Constrained content models• Allowed operations in authoring tools• Processing overrides as needed

26

Contexts in Mapless DITA• Contexts can take the place of maps for inferring:• Membership in a collection

• query as shorthand for “list of links of a kind”• Dynamic relationship of a topic to its peers• Ranking by relevance• Likely targets for *-ref resolution (xref, conref, link)

• How:• Depending on storage, build query functions that create arrays of

values-of-a-kind. Use “set membership” logic to retrieve records of topics that match (effectively faceted search to generate a map of already-matching candidate topics).

• Likewise for properties or filtering conditions implied by context (user preference data, for example) 27

Processing in Mapless DITA• Remember “State Machine?” This is logic based on values!• Processing for specific applications is generally lighter weight• Only delta processing with application expectations is needed;

should be an override to standard processing templates• But even the library of “standard processing templates” can shed the

weight of processing that would be unused anyway.

• Is this a case of building “Yet Another DITA Toolkit?” • No different from vendors bringing competitive features to market.

The content should process in any environment.

• The question is, • Does #MaplessDITA help solve a problem that perhaps only you

have? If it does, get your groove on!28

With this proviso:

“Make things as simple as necessary, but not simpler.” Einstein’s Razor, dulled by Day #MaplessDITA

29

Some Efforts• TLoWiki collaboration site for XML Press “The Language of”

book series (using a tlotermtopic specialization that drives form-based editing)

• Dynamic DITA Document Display demo site for a browser-based transformation engine that drives VMTurbo help.

• LightWeight DITA, explained by Michael Priestley

30

Questions?

• Fini!

31

Backup

32

DITA’s Architecture• The Collection (map) and the Instance (topic) • DITA models the RESTful Web

• The Shape Shifter • DITA models the organization’s business requirements

• The Assimilation of ‘The Build’• Most DITA applications follow a common processing model that

derives final property values from the map context. This is “wicked powerful.”

33

Tools of DITA• The Source:• Standard XML distinguished by DITA features

• architectural forms based on class attribute• extensibility by specialization• element-level reuse by conref

• Can be edited in any XML editor; best if also DITA-aware• Capable of file-based storage; does not pre-req CMS

• The Build:• Based on compile model similar to programming• Popular example: DITA Open Toolkit

• The Deliverable:• Declarative, deterministic (separate compiles for different goals)

34

Information Architecture?

• DITA’s base design is neutral regarding Information Architectures• Repeat. Memorize!

• Yes, DITA’s first specializations supported Minimalism and popular Infotypes, an approach still widely used:• Concept• Task• Reference

• But, the base topic and map can extend to each new IA as needed. 35

Transition thought: Ley Campoamor

“In this treacherous world nothing is truth or lie; everything depends on the color of the glass through which one looks.”

• Switching glasses now…

36

A job for State Machines

• Inputs are triggers to transition from one state to another • (such as temperature transitions in a thermostat)

• A State Transition Table defines these context-based behaviors:

Current State Input Next State Output

Read “Edit”Control In-edit

Load file from storage into editor session

In-edit

“Save as”Control In-edit

Save contents to new storage location; remain in In-edit state

“Save”Conrol Read

Save contents to current storage location; return to Read state

37