Introduction

This document explores the potential utility of DITA (Darwin Information Typing Architecture) for ITSM related information and knowledge development. DITA, as a structured documentation architecture based on an industry recognized open-source standard, provides a solid platform for consistent, schema compliant, information development. It offers prospects for content re-use and single-sourced output generation for publishing in multiple formats.

  1. About DITA
  2. Advantages for ITSM documentation


About DITA

DITA is an XML-based architecture for authoring and publishing topic-oriented, information-typed, content. While it has been initially driven by the requirements of large-scale technical documentation, it is applicable to any kind of publication or information where modular information topics can be identified and developed. Examples include help guides, standards and specifications, policies and procedures, technical glossaries, technical and business reports, and more. DITA is well fitted to flexibly support incremental information and knowledge development.

DITA topics are arranged into maps; combining hierarchic, nested, and sequential structures. Maps can be published to a avriety of forms from the same source; such as PDF, HTML, CHM (HTML Help), Web Help, SCORM (Sharable Content Object Reference Model -- an e-learning content set of standards), and several others. DITA text-based source markup is transformed into publishable media via specialized, open source, Java processors that are integrated into almost any DITA editor. Ouput customization takes place by editing transformation and/or style sheets, depending on the format of desired output.

DITA was originally developed by IBM and was later donated to OASIS (Organization for the Advancement of Structured Information Standards), which is currently the official standards body responsible for its development and specifications. There are current initiatives to expand the adoption of DITA for structuring and linking information in various industries and business environments (e.g. Learning By Wrote and DITA4all, whose misson is to make DITA an affordable option for structured documentation by large and small organizations alike.).

Main DITA content units

Topics are the main reusable authoring units. A topic is meant to be a self-contained information module of a fairly limited size (to maximize potential re-use). All DITA topics have the same basic structure: a title and an optional content body. The body of different types of topics contains a structure of elements that is mot fitted to support the respective content type. Topic elements are analogous to HTML tags, except that they vary depending on topic type, as opposed to HTML, which is defined by a single schema.

Topics can be generic or more specialized. Specialized topics represent more specific information types or semantic roles. The main DITA specialized topic types include Concept, Task, Reference, and Glossary. The DITA standard contains many more specialized topic types that are recognized by DITA editors and supported by DITA transformation tools. DITA allows Information designers and architects to further specialize any standard topic, so that it would serve a specific knowledge domain and/or support specific structural constraints. Somewhat like databases, topic vocabulary and structural grammar is defined by a schema.

The following is a description of the main specialized topic types:
  • Concept topics provide background that helps readers understand essential information about a product, a service, a process, a function, or any other conceptual or descriptive information. Conceptual information helps readers map their knowledge and understanding to the tasks that need to be performed to acheive an objective.
  • Reference topics provide quick access to factual information, possibly in support of the performance of a task or the management of a process. Reference topics may provide lists and tables that include specifications and constraints on utility or performance, and other data that is often “looked up” rather than memorized.
  • Task topics are the essential building blocks to provide procedural information. A task information type answers the "How to?" question by providing precise step-by-step instructions, actions that must be performed, and the order in which the actions must be performed. The task topic includes sections for describing the context, prerequisites, expected results, and other aspects of a task. Tasks may contain more granular, similarly structured sub-tasks.
  • Glossary topics allow authors to define terms, either within individual topic files or as a group within one topic file. The flexible granularity provides authors with freedom of identifying their "reusable" information unit (being a single term, a group of terms, or a set of glossary groups).
  • Composite topics allow authors the freedom to combine any number and type of topics within a single topic file, in an arbitrary order. This case may arise when needing to generate a single HTML output file, for example, or possibly when the constituent topics content is of limited size and exhibits strong intra-topic relations.

Maps are used to organize topics into a combination of hierarchy and sequence to be used for producing output of any of the fore mentioned forms. Maps may be nested within broader maps and they feature map-level (inter-topic) linking mechanism of related topics.

DITA main features

  • Minimalism: encourages containing typed units of information within concise topics that can be as much as possible self standing.
  • Contente re-use: well written topics may be combined and/or arranged in different ways within a topic map to generate multiple documents targeting different purposes or audience, while avoiding to re-edit content.
  • Single sourcing: DITA authored topics and maps can be funneled into a variety of output forms and media without having to modify the source or to use different specialized editing platforms.
  • Conditional processing: processing directives may be used within topics and/or maps to enable generating output that may or may not contain specific content units according to preset conditions.
  • Specialization: The specialization feature of DITA allows for the creation of new element types and attributes that are explicitly and formally derived from existing types. The resulting specialization allows for the interchange of all conforming DITA content across a certain community, with common authoring rules and processing for the specialized DITA content.
Parent topic: Introduction
Previous topic: Introduction
Next topic: Advantages for ITSM documentation


Advantages for ITSM documentation

ITSM related documention may be categorized in the following way:
  1. ITSM standards and specifications documents such as those produced by OGC and itSMF.
  2. ITSM knowldge development and management in the form of informative and analytic documents (books, articles, ...) that educate practitioners about the value and methodology of adopting best practices. An example is the set of downloadable documents at ITSM portal.
  3. ITSM gloassaries and dictionaries defining and maintaining best practices terminology, which may be produced as stand-alone books or as appendices within books.
  4. Actual ICT provider organizational specifications of ITSM policies, processes, and procedures. Preset templates can be written to enable encouraging (or enforcing) conistent editing and publishing environments within an rganization or across related organizations.

DITA can be effectively applied to harmonize and maintain any of the above mentioned document types. Each of the following chapters elaborates the exploration of DITA utility towards the respective type of documentation.

Parent topic: Introduction
Previous topic: About DITA
Next topic: Documenting ITSM standards and best practices


Documenting ITSM standards and best practices

Standards documents present clearly written content, with a well thought strcuture that tends to repeat throughpout volumes of documentation. DITA can be of value in several ways:
  • Containment of conceptual modules that could be re-used in multiple contexts
  • Maintaining consistent staructure with little repetitive manual intervention
  • Publishing current versions identically in both PDF and HTML (or any Help) formats


ITSM knowledge development with DITA

In the recognized knowledge pyramid model, knowledge is composed of information. DITA topics feature modular and re-usable information containers, out of which different harmonized knowledge dissemination chanels can be synthesized.

Once maps are setup and output documents are generated, editing a topic or re-arranging a book map, can be seamlessly propagated to the publishing medium by simply re-generating output.

DITA source topic and map editors are abundant and inexpensive. Output processors are available as part of the DITA Open Toolkit. There are three steps involved in applying DITA to a knowledge portal like the ITSM Portal:
  1. Structuring information content into typed topics
  2. Setting up maps to generate documents (knowledge streams) addressing different isseus or targeting different readrship
  3. Modifying default stylesheets for PDF and HTML if a specific "distinct" styling is required


Building ITSM glossaries with DITA

This is an area that is well supported by DITA, with the glossgroup and the glossterm topic types and their various content elements. Glossary groups can be combined into different sets and can be included in different maps to suit the desired variety of reference material readership. Granularity of re-use may range from a single term to hundreds of terms to hundreds of groups of terms. A DITA glossary is likely to form an appendix at the end of a document. However, same can be arranged in a DITA bookmap to produce technical and regulatory service management dictionaries and encyclopedia.

For illustration, the source markup of the following sample glossary is included here below

<!DOCTYPE glossgroup PUBLIC "-//OASIS//DTD DITA 1.2 Glossgroup//EN" "glossgroup.dtd">
<glossgroup id="glossgroup.ITIL_common">
    <title>Glossary of common ITIL terminology</title>
    <glossentry id="glossentry.service">
        <glossterm>Service</glossterm>
        <glossdef>A means of delivering value to customers by facilitating outcomes the customers
            want to achieve without the ownership of specific costs and risks.</glossdef>
    </glossentry>
    <glossentry id="glossentry.value">
        <glossterm>Value</glossterm>
        <glossdef>Consists of two core components: utility and warranty.</glossdef>
    </glossentry>
. . .
. . .
</glossgroup>
  1. Glossary of common ITIL terminology


Glossary of common ITIL terminology

Parent topic: Building ITSM glossaries with DITA
Previous topic: Building ITSM glossaries with DITA
Next topic: ITSM P&P templates

Service

A means of delivering value to customers by facilitating outcomes the customers want to achieve without the ownership of specific costs and risks.

Value

Consists of two core components: utility and warranty.

Utility

The value that the customer receives.

Warranty

How the value is provided.

Process

A structured set of activities designed to accomplish a defined objective. Processes are measurable, provide results to customers or stakeholders, are continual and iterative, and are always originating from a certain event.

Function

A team or group of people and the tools they use to carry out one or more processes or activities.

Process owner

Responsible for the process results.

Process manager

Responsible for the realization and structure of the process, and reports to the process owner.

Process operatives

Responsible for defined activities that are reported to the process manager.

Procedure

A specified way to carry out an activity or a process. It describes the “how”, and can also describe “who” executes the activities. A procedure may include stages from different processes.

Work instructions

A set of tasks that defines how one or more activities in a procedure should be executed in detail.

Role

A set of responsibilities, activities, and authorities granted to a person or team. One person or team may carry multiple roles.

Job position

Traditionally recognized as tasks and responsibilities that are assigned to a specific person.

Communication

A formal structure that includes reporting, meetings, online facilities, and notice boards.

Project

A temporary organization with people and other assets required to accomplish a defined objective.

Program

A number of projects and activities, which are planned and managed together to achieve an overall set of related objectives.

Portfolio

A set of projects and/or programs, which are not necessarily related, brought together for the sake of control, coordination, and optimization of the portfolio in its totality.


ITSM P&P templates

Policies are high-level organization-wide practices. Processes are generically specified by service management best practices and standards, with automation in mind to implement their logic and enforce their use. Procedures and consequent work instructions specify the human implementation of polices and processes. Policies can be written in DITA as collections of concept and reference topics, arranged in maps that reflect a logical hierarchy of corporate wide expectations of (IT) staff, and possibly corporate regulations in dealing with clients and business partners.

Procedures lend themselves to what DITA has been used for most since its inception. In spite of being a generic document architecture, DITA started with the task topic in mind, to support user, technical, and developer help guides of arbitrary complexities. task topic skeletons are very rich with elements that support sub-tasks and steps (for work instructions), pre and post requisties, results, and many more. Task topics are an excellent means of documenting, publishing, and managing corporate service provider procedures; specially those followed by contact center agents and tier-1 and 2 support staff, who are often not technical enough to action problem management spontaneosuly. The flexibility of easy single-sourced updates and the extensive linking capability make a very good case for ITSM procedures being implemented as DITA task topics.

Processes are probably the element that receives least added value of existing DITA topics. A process is a sustained activity with states, transitions, use cases, and instances. In ITSM contexts, they are often implemented as intranet applications/services. Process description is usually carried using UML activity diagrams. Other UML constructs are used to specify the correpsonding software implementation. Although there have been few debates, current DITA domain-specific (software) information types do not support UML constructs. They are rather geared towards documenting user interface constructs.

The application of DITA towards the actual organizational specification of P&P may be a contributor in more than one facet: from actual documentation of existing or evolving content, through acting as empty templates preset to support different practices, all way to being further specialized to name new elements that match a service provisioning branch of knowledge or a particular large organization (e.g. governmental) P&P naming and documenting conventions.

  1. How would a typical template work


How would a typical template work

In this broad example, individual topics will be authored separately for each item of each service lifecycle phase. Empty topic skeletons (templates) will be available for authors to elaborate how their own organizations conceive and implement each of these items.

Each of the above topics can link to detailed task topics that specify the implementation of underlying procedures and work instructions. Also, these topics can be prepared ahead as skeleton templates.

Next, a map (or a composite topic) would be constructed for each function or process that belong to the lifecycle phase.

Finally, an overall map would be constructed to contain all the lifecycle phases (as nested maps), thus containing an overall descripton of the organizational specification of its ITIL functions and processes implementation.

Parent topic: ITSM P&P templates
Previous topic: ITSM P&P templates

The added values of DITA-based specification templates

Following is a summary of the potential added values in case of this example:
  • Procedure and work instruction topics, the lowest level in this hierarchy, will be easily maintained and updated.
  • Procedures and work instructions can be arranged in arbitrary ways to meet the work requirements of different service management entities in the organization.
  • Higher level maps can also be arranged and published in several ways to meet organizational requirements.
  • All generated output can be "identically" (re)published in PDF, HTML, or WebHelp formats; upon updating a topic or a map, without needing to edit any other topic (information unit) other than the ones concerned.
  • Minor updates to a standards version can be easily accomodated. Major updates will build upon the established authoring conventions and will be easier and less costly to document and maintain.

An example template for specifying ITIL functions and processes

Service Strategy

Financial Management
  • Introduction
  • Basic concepts
  • Activities
  • Inputs and outputs
Service portfolio management
  • Introduction
  • Basic concepts
  • Activities
  • Inputs and outputs
Financial Management
  • Introduction
  • Basic concepts
  • Activities
  • Inputs and outputs
Demand Management
  • Introduction
  • Basic concepts
  • Activities
  • Inputs and outputs

Service Design

. . .

Service Transition

. . .

Service Operation

. . .

Continual Service Improvement

. . .