What is DITA? And Is It Right for Your Team or Project?

© 2014 Toni Mantych

What Is DITA? And Is It Right for Your Team or Project?

Toni Mantych

Willamette Valley STC March 13, 2014

© 2014 Toni Mantych § Slide 2

Who I Am

•  Writing professionally > 20 years –  Technical writing focus > 13 years –  For last 10+ years, keen interest in tools/technology

•  Teaching at Portland State University since 2007 –  A range of courses in the graduate Professional and

Technical Writing Program –  Mostly in-person, some blended and online courses –  Teach DITA every winter (just finishing up for 2014)

•  Currently, Information Architect, ADP (A Fortune 500 company) –  Moving department of 60+ writers to DITA/XML and Structured Authoring –  Work remotely from my home in Beaverton, OR; team is (mostly) in NJ, GA

•  Other Stuff –  Former Competition Manager, Tools & Technology columnist, and President of the

Willamette Valley STC chapter –  Certified Project Management Professional (PMP) since 2010 –  AIIM-Certified Taxonomy and Metadata Practitioner since 2012 –  MA and ABD in English Literature (Taught literature and composition > 10 years) «


What I Will Cover

•  A brief history of the origin and evolution of DITA •  Some of the key characteristics of DITA

•  Some of the major benefits of using DITA

•  Why DITA is not equally well-suited to every project or team «


What I Will Not Cover

•  How to implement DITA •  Details of the architecture

•  Specific tools to support DITA

•  How to author in DITA

But, I will tell you when and where you can get some hands-on training!


What Is DITA?

•  Darwin Information Typing Architecture •  One possible architecture that can be used to structure

information (there are others!) –  A modular, topic-based architecture –  Based on an information typing approach –  Developed by IBM specifically for “for authoring, producing,

and delivering technical information.” –  Based on a particular “markup language” called XML

More on the “Darwin” part later.


The History of DITA: From IBM to OASIS to v1.2

•  Late 1990s: IBM begins developing DITA

•  2004 –  IBM donates DITA to OASIS (the Organization for the Advancement of Structured Information

Standards), “a not-for-profit that drives the development, convergence and adoption of open standards for the global information society”

–  The OASIS Technical Committee for DITA is formed to manage the DITA standard

•  2005 –  OASIS approves DITA v1.0 standard –  SourceForge begins DITA Open Toolkit support; DITA OT v1.1 released (now up to v1.8)

•  2006: OASIS launches DITA.XML.org

•  2007: DITA V1.1 standard is approved by OASIS (includes Bookmap specialization)

•  2010: DITA V1.2 standard is approved by OASIS. It includes: –  Indirect linking with keys –  Enhanced glossary support, including acronyms –  New industry specializations (Learning & Training, Machinery) –  New support for controlled values/taxonomies (Subject Scheme specialization)

•  2014: DITA 1.3 is under development; includes plans for a “Lightweight DITA” standard. «

Source: Wikipedia; http://www.ibm.com/developerworks/xml/library/x-dita1/


DITA Today

•  Continued rise in use, due to changing content requirements –  Users demanding more “intelligent” content –  Organizations need to develop more—and more targeted—content, often

with the same (or fewer) resources –  Most products, services, and information now have global audience –  Information channels and display devices proliferating rapidly

•  Has reached and surpassed “critical mass” in terms of adoption –  See this informal list of companies believed (or confirmed) to be using DITA:

http://www.ditawriter.com/companies-using-dita/ –  More job postings request or require DITA experience –  Many DITA-aware authoring tools and content management systems now

available –  A wide community of users and consultants has emerged, as well as

numerous online resources –  Multiple full-length books on DITA are now available –  DITA is the topic of many industry conference presentations and training

workshops—and even has dedicated conferences «


DITA as a Solution to Multiple Requirements


Modular, Topic-Based Approach: Why?

•  Long narratives w/linear logic less effective for Web and mobile users

–  Limited real estate –  Random access, no guaranteed context

•  User behaviors & expectations changed –  Short attention spans –  Want targeted information & high findability

•  Products more modular –  Packaged in multiple configurations –  Modular content can “travel with” the product

modules

•  Collaborative authoring difficult in long source files

•  Re-use easier and more efficient with topics –  Due to smaller chunks, context-neutrality –  In turn, content development and translation/

localization costs lower «


DITA for Modular, Topic-Based Authoring

•  Content is authored in “topics” –  Basic “unit of reuse” –  Three predefined topic types for technical

information (concept, task, reference); more can be created

•  “DITA maps” group topics into deliverables –  Easy to mix and match topics in different

collections and sequences –  Maps are also reusable modules

•  DITA has powerful linking capabilities –  Links help users navigate through the

individual topics to find information that meets their specific information needs

–  Important because narrative transitions and linear reading are gone

•  Single map can be transformed into many outputs

–  Based on different media types (HTML pages, tri-pane help systems, PDF, etc.).

–  With different look-and-feels «


Standards-Based, Extensible, Semantically Rich: Why?

•  Best to use established & governed standards whenever possible –  No dependency on proprietary format and/or vendor who controls that format –  Greater chance of stability –  Allows participation in future/development –  Increases likelihood of tool/vendor support and of integration with other systems

•  Best to use an extensible standard –  For “future proofing” –  Minimizes likelihood of needing to change

approach as requirements change

•  Best to use standard that supports rich, semantically based metadata

–  Allows complex, technologically based manipulation of content based on conditions and other metadata

–  Should be based on semantics rather than presentation or relationships, to maximize reusability of content «


DITA Is Standards-Based, Extensible, Semantically Rich

•  DITA is based on XML, which is an established standard –  XML is a non-proprietary markup language governed by a standard –  Supports rich (and extensible) metadata –  Supports creation of an extensible architecture of content elements –  Can be edited in a text editor or in graphical XML editors –  Is presentation-neutral, but can be transformed into a wide range of current (and

future) output media types –  Is widely used and easily consumed by other systems

•  DITA is a standard itself now, too –  Managed by OASIS –  Well-established, so it is easy to find

tools, training, vendors, support now –  Supports robust filtering (aka “profiling”

or “conditionalizing”) of content –  Non-proprietary and tool-agnostic «


Structured Authoring


Structured Authoring: What Is It?

•  What’s the big deal? Haven’t we always written in a structured way?

–  Middle school: The 5- paragraph essay (intro, 3 body paragraphs, conclusion)

–  High school: The lab report (title, intro, problem, hypothesis, material, method, data/results, analysis, conclusion)

–  Work: Templates for various deliverables (user guides, QRCs, online help, etc.) and style guides with rules about usage as well as structure and formatting

•  Clearly, we don’t have to use XML or DITA to write in a structured way.

But “Structured Authoring” is more just writing within a structural model.

Image source: http://tsediting.wikispaces.com/Five+Paragraph+Essay


How Is Structured Authoring Different?

•  Compliance with a defined structure is enforced by technology (rather than by human editors). You can’t deviate from it (easily, anyway).

•  Structure uses semantic tags that describe the content type and rhetorical function of each content element (e.g., “uicontrol” or “prerequisite”), rather than defining the look and feel of that element or a specific relationship or context (as, for example, HTML’s <h1> does).

•  Authors only have to focus on the semantic structure of their content as they write. They do not have to worry about “presentation” issues, such as typeface size, margins, page breaks, color schemes, etc.

•  The technologically encoded structure allows more advanced—and automated—manipulation, sharing, styling, profiling, and publishing of content. «


Structured Authoring: Why?

•  Improves content consistency and quality, and the user experience

•  Reduces cognitive load for authors, allows them to focus on content

•  Enables easier content reuse, which increases efficiency and reduces cost

•  Supports multi-channel publishing (by media or by look-and-feel)

•  Facilitates seamless content integration across systems«


DITA Supports Structured Authoring

•  Robust, mature, and stable set of content types and elements for tech content.

•  Many “DITA-aware” tools understand and enforce the architecture. These tools can also help authors troubleshoot validation errors.

•  Can be modified as specific information needs dictate, and/or as technology yields new delivery output formats.

•  Separates content from form—which helps authors focus on writing and facilitates reuse and multichannel publishing. «


Purpose-Built and Extensible: Why?

•  Purpose-Built –  Always better to start with something that

was created for what you are trying to do! –  No need to re-invent the wheel, but also

need to be able to adapt to your needs.

•  Extensible –  You can extend the architecture if you need

to. This reduces the one major risk of using a pre-defined architecture (namely, that the architecture won’t meet all your needs).

•  Benefits –  Saves implementation & development time –  Leverages cumulative industry wisdom –  Allows flexibility to meet unique/future

information requirements. «


DITA: Designed for Tech Comm, but Extensible

•  Designed for Tech Comm –  By IBM, initially for software docs –  Three information types for technical content

are excellent models for most use cases. –  DITA Open Toolkit comes with a set of OTB

transforms for common media types –  Still evolving—but with governance to ensure

compatibility. OASIS committee develops new domains, information types, elements, and attributes (e.g., Learning and Training; Machine Industry; “Lightweight” DITA)

•  Extensible and Specializable –  You can extend the architecture by adding

new information types and elements –  New types and elements can inherit

properties and relationships of the types and elements they are specialized from, so you don’t have to code every detail

–  New transforms can be created to support new media formats or presentation requirements «


DITA as a Solution to Multiple Requirements


What Implementing DITA Can Do

•  Enable single sourcing and content reuse –  Increase consistency –  Improve quality –  Reduce authoring, maintenance, and translation costs

•  Enable better content interoperability with applications and other systems (including products being documented, content management systems, translation management systems, search engines, and dynamic publishing engines)

•  Enable collaborative authoring

•  Reduce dependency on specific tools

•  Provide flexibility and “future proofing” «


If It’s So Great, Why Doesn’t Everyone Use It?

•  It is great, and I highly recommend it as the preferred way to go if you are starting a new documentation team that will:

–  Produce content that supports multiple types of users and/or multiple versions of a product

–  Have many writers –  Deliver content in multiple languages –  Publish to many different media and/or device types –  Will have a lot of content that is exactly—or nearly—the same across multiple

deliverables

•  If only one or two of the above statements apply to you, you won’t get to exercise all of DITA’s power, but DITA is still a fine option. «


If It’s So Great, Why Doesn’t Everyone Use It?

•  If you are an existing organization with a lot of existing content that you have to continue to maintain and develop, you’ll have to weigh the potential future benefits of DITA against the costs of migrating.

–  Migration is complex and can be costly. Here are just some of the steps: •  Create specializations •  Re-architect and/or rewrite existing content as necessary (esp. if unstructured) •  Convert source from HTML or Word or FrameMaker to XML •  Train writers in DITA, minimalism, reuse strategy, etc. •  Create custom transforms for each media type, delivery device, and look-and-feel •  Manage culture change/paradigm shift.

–  But the benefits—including, but not limited to, cost savings—can be huge over time, especially if:

•  You have a large number of writers and a large volume of content •  You have a high potential for content reuse across your deliverables •  You have to create a lot of similar-but-different versions of your content •  You deliver content in multiple languages

•  For more on deciding whether migrating to DITA makes sense: http://www.slideshare.net/Scriptorium/dita-or-not-to-dita. «


So, Why “Darwin”?

•  Many aspects of DITA rely on the concept of inheritance. –  Nested elements “inherit” attributes/characteristics

from their container elements. Child elements have the same attributes or characteristics as their parent elements (unless they you specify otherwise).

–  Specializations are customized “new” elements that are based on existing elements. One could say they are an example of adaptation.

–  As adaptations, specializations are based on and “inherit” most of the properties of the elements from which they are specialized, but they have some unique characteristics.

•  DITA itself continues to adapt and evolve! «


Evolutionary Adaptation = DITA Specialization?


Want to Know More?

•  Believe it or not, we’ve only just scratched the surface, even on a theoretical/strategic level.

•  Online resources: –  PDX DITA: http://pdxdita.ditamap.com –  DITA Users’ Yahoo Group:

https://groups.yahoo.com/neo/groups/dita-users/info –  Online Community for DITA OASIS Standard: http://dita.xml.org –  DITA 1.2 Specification:

http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html –  Tons more!

•  Books (for beginners) –  DITA Best Practices, Laura Bellamy et al, IBM Press, 2012 –  Introduction to DITA, 2nd ed., JoAnn Hackos, 2011 –  DITA 101: Fundamentals of DITA for Authors and Managers, Ann Rockley et

al, 2009


Want to Know More?

•  Upcoming 2-day workshop: Friday May 9 and Saturday May 10 –  Portland Metro location (TBD) –  8:30 AM to 5:00 PM each day (with morning, lunch, and afternoon breaks) –  Sponsored by WVC STC, taught by yours truly –  Hands-on! You will use a trial version of oXygen XML to:

•  Create and edit topics •  Create DITA maps •  Reuse topics and maps •  Single-source content below the topic level •  Conditionalize your output •  Generate deliverables in multiple media

–  Registration not yet open, but space will be limited –  Grab a handout to remind you to save the dates, then watch www.stcwvc.org

or the announcement list for full details. –  Let me know now if you have questions: [email protected].

What is DITA? And Is It Right for Your Team or Project?

Technology

dita v1

history of dita

evolution of dita

dita details

available dita

lightweight dita standard

reusable modules dita

key characteristics