what “model” dita specializations can teach about information modelinc

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

What "Model" DITA Specializations Can Teach Us About Information Modeling

Don Day | donrday@contelligencegroup.com | @donrday

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

About Adobe

2

>74 Offices in 43 Countries

Corporate Headquarters inSan Jose, California

Founded in December 1982

$4.06 billion in revenue in FY2013

>10,000 employees

Adobe donates a minimum of 1%of net income to philanthropy

We simplify complicated, inefficient, and expensive workflows.We enable more engaging, compelling content.We drive greater return from digital media and marketing investments.

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

Your Webinar Host

Maxwell Hoffmann Adobe Global Product Evangelist,

Technical Publishing (Tech Comm Suite)

Former Product Manager and Sales Training Directorfor Frame Technology

15 years in translation industry, working on “whatever documents walked through the door”

Trained over 1,200 people in hands-on, scalable publishing solutions

Claims to have published or touched up over 1,000,000 pages!

… and somebody here tonight knows MORE than HE does

3

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

About our Guest

Don Day 25 years involvement in IBM’s Information

Development tools and strategy

Inventor with patents related to content and UX

A contributor and founding Chair for the OASIS DITA XML markup standard

Consultant on strategy, technology, and best practices for optimizing the value and usefulness of unstructured data

Speaker and author on emerging publishing technologies

4

Information Modeling from the Demo DITA* Specializations Don Day,Contelligence Group LLC

* The Darwin Information Typing Architecture, an OASIS XML markup standard

Lead-up: High Octane Content• Adobe TechComm Central blog post:

http://blogs.adobe.com/techcomm/2014/06/high-octane-documents-june-12-dita-model-webinar.htmlImagine a Content Octane Rating that indicates whether content has the metadata and structural refinement necessary to keep the business engine running smoothly under load.• 85: Unleaded; Conventional text file• 87: Use of basic styling markers (HTML or Markdown)• 89: Use of semantic phrase markup (var, cite, kbd, code, etc.)• 90: Use of complex data models (e. g., structures for sections)• 91: Premium! Supports interaction with rules-driven processing

• What is the Content Octane Rating (COR) of your documents?

• Note also the formalized rating system, DITA Maturity Model

About This Presentation

There is value in having structured information. How to get started? We’ll cover:

1. High level goals of an Information Model2. Comparative overview of some sample designs

from the DITA community:• What were they thinking, good or bad?• How would I organize and structure my own content?

3. Summarize a design approach you can apply for your content

1. Goals of Information Models• “An Information Model is a set of principles that define how

you intend to structure the information you develop.”-- JoAnn Hackos, CIDM Newsletter, Feb. 2010

• It is a contract between the document and the outside world:• For querying into the document (not just full text search)• For processing the content in ways that support the business• For publishing the content as its readers need or prefer

A Model Is:A representation of the underlying Information Architecture. It helps:• Builders (authors, tool

vendors) to create conforming instances of the model

• Occupants (readers, publishing tools) to navigate and get best use of those facilities.

Photo credit: Cushing Memorial Library and Archives, Texas A&M /Foter / Creative Commons Attribution 2.0 Generic (CC BY 2.0)

An Information Model Promotes:

• Consistency of writing style• Readers can anticipate where they want to look• Separation of formatting concerns from the model itself

• Useful data types for processing:• Semantic intent for search relevance• Structure to indicate scope of relevant content

• Association of business rules to the content:• Management of translation process• Automation of workflow and QA controls• Automation of backup, version control• Ability to share interoperable content with business partners,

OEMs, and customers, as needed

Process enforcement

Traditional

Guides, templates, and manual verification

Automated

Information types, schemas and rules-driven processes

2. Comparative Review• Available Cases:• XML Applications and Initiatives (at last count, 594!)

• http://xml.coverpages.org/xmlApplications.html• DITA Open Toolkit plugins

• Various locations, but manageable number• We will go with DITA OT-compatible designs

• Methodology (CSI model):• The Lineup• Psychological Profile (What were they thinking?)• Motive (What were they trying to accomplish?)• Modus Operandi (How did they do it?)• Applicable Charges (What can we learn from mistakes and wins?)

The Lineup:

DITA Open Toolkit Plugins• For this particular lineup (a spectrum of quality):• Music: https://github.com/dita-ot/ext-plugins/tree/master/music• MsgRef:

http://sourceforge.net/projects/dita-ot/files/Plug-in_message%20specialization/

• Faq: https://github.com/dita-ot/ext-plugins/tree/master/faq• eNote: https://github.com/dita-ot/ext-plugins/tree/master/enote

• Known plugin repositories (some duplicates):• https://github.com/dita-ot/ext-plugins (models, extensions)• https://github.com/robander/metadita (extension points)• http://sourceforge.net/projects/dita-ot/files/ (stable releases)• https://groups.yahoo.com/neo/groups/dita-users/files/Demos/

Music plugin

Characteristic Assessment

Line of business Personal demo by Robert Anderson, DITA OT lead

Apparent business driver Reduce Robert’s time spent in teaching plugin concepts; exemplar for plugin authors (DTDs and processing hooks); enable greater DITA-OT uptake

Design methodology Model a typical “collector’s database” (portfolio)

Use of typed data Sorting CDs/songs by categories and types; extends <simpletable> as a relational database.

Usability Obvious, meaningful element names

Utility For CD/song collections, mainly of personal interest; as a teaching tool, highly useful

Compelling virtues Well documented; complete application with multiple outputs and even some editor support

Odious flaws None

https://github.com/dita-ot/ext-plugins/tree/master/music

Music DTD fragment• <!-- LONG NAME: Music Collection -->• <!ELEMENT songCollection (%title;, (%titlealts;)?, (%shortdesc; | %abstract;)?, • (%prolog;)?, (%songBody;)?, (%related-links;)?, • (%song-info-types;)* ) >

• <!-- LONG NAME: Music Body -->• <!ELEMENT songBody ((%section; | %simpletable; | %songList;)* ) >

• <!-- LONG NAME: -->• <!ELEMENT songList ((%songRow;)+) >•

<!-- LONG NAME: -->• <!ELEMENT songRow ((%song;)?, (%album;)?, (%artist;)?,(%genre;)?,• (%rating;)?,(%count;)?,(%playdate;)?)>•

<!-- LONG NAME: -->• <!ELEMENT song (%ph.cnt;)* >•

<!-- LONG NAME: -->• <!ELEMENT album (%ph.cnt;)* >•

<!-- LONG NAME: -->• <!ELEMENT artist (%ph.cnt;)* >•

<!-- LONG NAME: -->• <!ELEMENT genre (%ph.cnt;)* >•

<!-- LONG NAME: -->• <!ELEMENT count (%ph.cnt;)* >• • <!-- LONG NAME: -->• <!ELEMENT playdate (%ph.cnt;)* >

Music Instance

Msgref plugin

Characteristic Assessment

Line of business Software company (but could be hardware codes)

Apparent business driver Single source for content that appears in both product interfaces and in documentation (to lower translation redundancy, for example)

Design methodology Represent the Java Resource Bundle structure

Use of typed data Deliberate, strongly fielded (see the msgID “title”)

Usability Abbreviated element names (probably necessary due to wordiness of the domain, but an NLS issue);Difficult to write without a fielded editing tool.

Utility Very good fit for the designed purpose (hands-off reuse of message strings)

Compelling virtues Natural use of a “message” infotype and fields

Odious flaws Development costs for authors and tools interfaces

http://sourceforge.net/projects/dita-ot/files/Plug-in_message%20specialization/

msgRef DTD fragment• <!-- ============ Element definitions ============ -->

<!ELEMENT msg ((%msgId;), (%titlealts;)?, (%msgText;), (%prolog;)?, (%msgBody;), (%related-links;)?, (%msg-info-types;)*)><!ATTLIST msg id ID #REQUIRED conref CDATA #IMPLIED %select-atts; %localization-atts; outputclass CDATA #IMPLIED %arch-atts; domains CDATA "&included-domains;"><!-- Specialize msgId from title, require three specialized phrases in the title --><!ELEMENT msgId (((%msgPrefix;)*, (%msgNumber;)+, (%msgSuffix;)*)) ><!ATTLIST msgId %id-atts; %localization-atts; outputclass CDATA #IMPLIED><!ELEMENT msgPrefix (%ph.cnt;)*><!ATTLIST msgPrefix keyref CDATA #IMPLIED %univ-atts; outputclass CDATA #IMPLIED><!ELEMENT msgNumber (%ph.cnt;)*><!ATTLIST msgNumber keyref CDATA #IMPLIED %univ-atts; outputclass CDATA #IMPLIED

msgRef instance

FAQ plugin

Characteristic Assessment

Line of business Support organizations; call centers

Apparent business driver Capture resolved issues as new best practice responses for subsequent problem calls

Design methodology Assess the structure of conventional FAQs on the Web, model the design as a DITA specialization

Use of typed data Rich information type (top-down) and categories; some internal semantic terms as well

Usability Is functional, obvious; could be extended as needed

Utility The authoring problem it addresses is already solved by knowledge base applications; better suited as a “delivery aggregator”

Compelling virtues Simple, clear information model

Odious flaws None; could actually be used for “DITA on the Web”

https://github.com/dita-ot/ext-plugins/tree/master/faq

FAQ DTD fragment• <!-- ============ Element definitions ============ -->• <!ELEMENT faq ((%title;), (%titlealts;)?, (%shortdesc;)?, (%prolog;)?, (%faqbody;), (%related-links;)?, (%faq-info-types;)* )>• <!ATTLIST faq id ID #REQUIRED• conref CDATA #IMPLIED• outputclass CDATA #IMPLIED• xml:lang NMTOKEN #IMPLIED• %arch-atts;• domains CDATA "&included-domains;"• >

• <!ELEMENT faqbody ((%faqgroup;)+ | (%faqlist;))>• <!ATTLIST faqbody %univ-atts;• outputclass CDATA #IMPLIED• >

• <!ELEMENT faqgroup ((%title;), (%faqlist;))>• <!ATTLIST faqgroup spectitle CDATA #IMPLIED• %univ-atts;• outputclass CDATA #IMPLIED• >

• <!ELEMENT faqlist (%faqitem;)+>• <!ATTLIST faqlist relcolwidth CDATA #IMPLIED• keycol NMTOKEN #IMPLIED• refcols NMTOKENS #IMPLIED• %display-atts;• %univ-atts;• spectitle CDATA #IMPLIED• outputclass CDATA #IMPLIED• >

• <!ELEMENT faqitem ((%faqquest;), (%faqans;), (%faqprop;)?)>• <!ATTLIST faqitem %univ-atts;• outputclass CDATA #IMPLIED• >

FAQ instance

Enote plugin

Characteristic Assessment

Line of business Mimics existing email tools; demonstrates using content structures for header metadata

Apparent business driver Demo only; not in response to a business need

Design methodology Demonstrate “XML data islands” within standard note structures.

Use of typed data Yes, for the header data islands

Usability Good to see how content can be used for data; to some extent, this need is handled by DITA 1.2 +

Utility Not a real application

Compelling virtues Good teaching tool (like a car engine cut in half)

Odious flaws No longer a best practice for embedded data; use the new <data> element

https://github.com/dita-ot/ext-plugins/tree/master/enote

Enote DTD fragment• <!-- ============ Element definitions ============ -->• <!ELEMENT enote ((%subject;), (%prolog;)?, (%notedetail;), (%enote-info-types;)* )>• <!ATTLIST enote id ID #REQUIRED• conref CDATA #IMPLIED• outputclass CDATA #IMPLIED• xml:lang NMTOKEN #IMPLIED• %arch-atts;• domains CDATA "&included-domains;"• >

• <!ELEMENT subject (#PCDATA)*>• <!ATTLIST subject %id-atts;• outputclass CDATA #IMPLIED• >

• <!ELEMENT notedetail ((%noteheader;), (%notebody;)?)>• <!ATTLIST notedetail %univ-atts;• outputclass CDATA #IMPLIED• >

• <!ELEMENT noteheader ((%From;), (%To;)?, (%Cc;)?, (%Bcc;)?, (%Date;)?, (%delivery;)?, (%references;)?, (%attachments;)?)>• <!ATTLIST noteheader %univ-atts;• outputclass CDATA #IMPLIED• >

• <!ELEMENT From (#PCDATA | %recipient;)*>• <!ATTLIST From %univ-atts;• outputclass CDATA #IMPLIED• >

Enote instance

3. A Design Approach for DITA

1. Determine the business imperative2. Identify stakeholders3. Get sponsorship and team4. Analysis & design: • Top-down: Identify information types and content structures• Bottom-up: Identify keywords and data types• Find a good-enough depth of concerns (Best is enemy of good)• Test usability of names (elements, attributes, value keywords)• Test usability of design in an actual XML editor• Test publishing/processing/search effectiveness• Document early; capture lessons often

5. Report up6. “Make it so, Number One!”

On your own:Smaller project ideas• Recipes• Meeting minutes• Database for collections (action figures, cameras, stamps, etc.)• APIs• Unix-style “man pages”• Trading cards, baseball or Pokémon style• Neighborhood newsletter/web site

• “Kleine Kinder, kleine Sorgen, große Kinder, große Sorgen.“

On your own:New or reused?• Port an existing design to your framework (for example, apply

this design to a DITA framework: http://www.happy-monkey.net/recipes/)

• Represent an existing process in the model (basically what the enote demo did)

• Port existing to your framework, then augment with your process requirements

On your own:Considerations• Ease of authoring• Clear distinction of “things” vs “properties”• Naming: clarity vs verbosity• Balance between precision and usability:• Avoid needing to parse key data in your processor

e. g. <date>June 12 2014</date> for Europeans

• On the other hand, avoid too much detail: <sentence>

<word>This</word> <word>is</word> <word>just</word> <word>wrong!</word>

</sentence>

Here be Dragons!• How will your chunks be used? Each new process represents a

new “application context” for the collection.• What business rules need to be supported by the process? Are

they part of the application-level information model?• Roll your own or involve a consultant?• What are the costs of support and maintenance?• What are the costs of training and getting up to speed?

Wrapping up• Skills you may want to learn:• UML or “Data Modeling 101”• XML schema design• Editor configuration (EDDs for FrameMaker)• Web forms for simple fielded interfaces

• Where to find outside help• https://groups.yahoo.com/neo/groups/dita-users/info• LinkedIn XML- and DITA-related groups• Support lists for the authoring and CMS tools you have

Questions!

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

Upcoming webinars Spring/Summer 2014

June 12: What ‘Model’ DITA Specializations Can Teach Us About Information Modeling = http://adobe.ly/1rppQtY

June 20: Recording webcam video for tech comm = http://adobe.ly/1pr6WFJ

July 10, Sept 24, Oct 31 & Dec 4: 4x Series: Tech Challenges: Surfing and Diving Deep = http://adobe.ly/1rpq7Nq

2x series: Strategies for Success with RoboHelp 11 ProjectsTanner Services Corp: July 24, Aug 21 = http://adobe.ly/1ptKcVn

If you’re viewing THIS recording after dates listed, go to: http://adobe.ly/Pbdp0J

34

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

Useful Links Regarding FrameMaker 12

Recorded FM Launch webinar with timeline: http://adobe.ly/1gvr4lU

FrameMaker 12 Reviewer’s Guide = http://adobe.ly/1i8kS0h

FM 12 Version Comparison Chart = http://adobe.ly/1crT6X8

FrameMaker XML Author 12 Home = http://adobe.ly/1i8lvXG

FrameMaker XML Author 12 FAQ = http://adobe.ly/1i8lVxj

FrameMaker 12 AdobeTV show = http://adobe.ly/1i8FTbe

FrameMaker XML Author 12 AdobeTV show = http://adobe.ly/1gnRUMB

35

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

Relevant Recorded Webinars

FrameMaker 12 Feature Focus 2): 12 New Templates with Hidden Power!Guest Bernard Aschwanden of Publishing Smarterhttp://adobe.ly/1nBSDwU

Wow! FrameMaker 12 in just 45 minutesMaxwell Hoffmannhttp://adobe.ly/1sTr55A

FrameMaker 12 Feature Focus 5): Customizing Published Output to On-Line FormatsMaxwell Hoffmannhttp://adobe.ly/1qGLVqZ

36

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

Microsite: www.authorxml.com

37

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential. 38

Q&A

© 2012 Adobe Systems Incorporated. All Rights Reserved. Adobe Confidential.

Contact Information

39

InformationDon Day@donrday

Email donrday@contelligencegroup.comWWW: http://contelligencegroup.comSample: http://expedita.info/LinkedIn: http://www.linkedin.com/in/donrday

Maxwell HoffmannAdobe Systems, Inc.Product Evangelist

Blog blogs.adobe.com/techcomm

Twitter @maxwellhoffmann & @AdobeTCS

Email mhoffman@adobe.com Web www.adobe.comLinkedIn www.linkedin.com/in/maxwellhoffmannFacebook Adobe Technical Communication Professionals

Previously recorded eSeminars: http://adobe.ly/qo3pzc

Calendar of upcoming eSeminars: http://adobe.ly/xdzOYa