DITA-Einführung

Heinz Wittenbrink

2020-11-14

Intro

Bild: https://www.dita-ot.org/

D arwin: Evolutionäre Weiterentwicklung
I nformation: Praktisch und mehrfach nutzbare Inhalte
T yping: Concept, Task, Reference als Grundtypen
A rchitecture: Komponenten für Wiederverwendung und Publikationen

Orientiert an: Sarah O’Keefe, DITA 101 webcast

Zielsetzung

Grundwissen über DITA
Kenntnis von Anwendungsfällen und Business Cases
Überlegungen zu DITA in der Content-Strategie

Einführung von Sarah O’Keefe

DITA 101 - YouTube

DITA-Basics

Warum DITA?

Wiederverwendbarkeit von Inhalten
Wiederverwendbarkeit von Modellen
Trennung von Modell und Präsentation
Orientierung an digitaler Ausgabe statt an papier-basierten Formaten

Typische Vorteile

die Veröffentlichung einer Menge von Informationsprodukten für unterschiedliche Benutzergruppen und über mehrere Releases hinweg unterstützen
neue Zusammenstellungen von Inhalten einführen, die neue Inhaltstypen erfordern (z.B. Hardware Dokumentation, Geschäftsprozesse usw.)

Gnostyx DITA Demonstration Documents

Wie funktioniert DITA?

Bild: Adobe Systems

Die Hilfe zu Adobe Framemaker ist generell eine gute Einführung in DITA https://help.adobe.com/en_US/framemaker/2017/using/index.html

DITA Use Cases

Freescale Semiconductor Inc

Esko (Infografik)

Skyward Case Study

Design-Prinzipien

Minimalismus
Information Mapping
Vererbung/Objektorientierung

Minimalismus

Nach JoAnn Hackos

Principle 1: Choose an action-oriented approach
Principle 2: Anchor the tool in the task domain
Principle 3: Support error recognition and recovery
Principle 4: Support reading to do, study, and locate

Zitiert nach: What is Minimalism? | Every Page is Page One

People are situated in a world more real to them than a series of steps, a world that provides rich context and convention for everything they do. People are always already trying things out, thinking things through, trying to relate what they already know to what is going on, recovering from errors. In a word, they are too busy learning to make much use of the instructions. (J.M.Carrol)

What is Minimalism? | Every Page is Page One

Information Mapping

Video: Information Mapping - What is it? Why use it? - YouTube

Information Mapping® provides a number of tools that help you to analyze, organize and present information:

Information Types […] Research-Based Principles […] Units of Information […] Presentation Modes […]

Quelle: The Information Mapping® Method - Information Mapping

Vererbung

Quelle: Wikimedia Commons, Urheber: User:Cactus26,

In object-oriented programming, inheritance is a way to form new classes using classes that have already been defined. …

In DITA, child topics or elements inherit attributes from their parents. For example, metadata applied to a section of a DITA file will automatically be applied to topics contained in the section.

Inheritance also plays an important role in DITA specialization, which allows you to extend a base topic to match your specific requirements by defining only the differences between it and its base topic; the bulk of the specialized definition is inherited.

DITA-Basics in Code-Beispielen

(Quelle: Darwin Information Typing Architecture - Wikipedia)s

Ditamap file (table of contents) sample

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map id="map" xml:lang="en">
  <topicref format="dita" href="sample.dita" navtitle="Sample" type="topic"/>
</map>

Hello World (topic DTD)

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic xml:lang="en" id="sample">
  <title>Sample</title>
  <body>
  <p audience="foo">Hello World!</p>
  </body>
</topic>

Topics haben eine id.
Die audience kann insgesamt oder bei einzelnen Elementen festgelegt werden.

Example of conditionalized text:*

<?xml version="1.0" encoding="UTF-8"?>
<p audience="foo">
This is an information useful for the foo audience!
</p>
<p audience="bar">
This is an information useful for the bar audience.
</p>

Topics

A topic is a unit of information with a title and content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit.

Quelle: DITA topics

Topics are the basis for high-quality information. They should be short enough to be easily readable, but long enough to make sense on their own.

Quelle: DITA topics

Information typing is the practice of identifying types of topics that contain distinct kinds information, such as concepts, tasks, and reference information. Topics that answer different kinds of questions can be categorized as different information types. The base topic types provided by DITA ( a generic topic, plus concept, task, and reference ) provide a usable starter set that can be adopted for immediate authoring.

Quelle: DITA topics

Grundlegende Topic-Typen

Concepts: DITA concept topics answer “What is…” questions. They include a body-level element with a basic topic structure, including sections and examples.

Quelle: DITA topics

Tasks: Task topics answer “How do I?” questions, and have a well-defined structure that describes how to complete a procedure to accomplish a specific goal.

Quelle: DITA topics

Reference: Reference topics describe regular features of a subject or product, such as commands in a programming language.

Quelle: DITA topics

Struktur, Content, Module

Struktur von Topics in der DITA-Dokumentation: Topic structure
Inhalte eines Topic in der DITA-Dokumentation: Topic content

Publizieren

Quelle: DITA Open Toolkit

Maps

DITA map files are used for defining the topics of a publication, specifying the topic sequence, and controlling linking between topics.

Defining the topics
Specifying the sequence
Controlling linking

Teile von Maps

Topic Manifest: definiert die Topics in einer Publikation
Hierarchy Definition: Reihenfolge, Bedeutung, Navigationswege
Link-Beziehungen

Siehe zu den Maps: Purpose of ditamap files

Die Maps bestehen vor allem aus topicref-elementen. Sie können hierarchisch angeordnet sein und zu relationship tables gehören.

Beispiel topic map

<map>
  <title>DITA for the Impatient</title>

  <topicmeta>
    <author>Hussein Shafie</author>
    <publisher>Pixware</publisher>
    <critdates>
      <created date="October 7, 2009"/>
    </critdates>
  </topicmeta>

  <topicref href="introduction.dita"/>
  <topicref href="topics_and_maps.dita"/>
  <topicref href="topic.dita">
    <topicref href="topic_structure.dita">
      <topicref href="samples/sample_topic.dita" toc="no"/>
    </topicref>
    <topicref href="block_elements.dita"/>
    <topicref href="inline_elements.dita"/>
    <topicref href="link_elements.dita"/>
  </topicref>
  .
  .
  .
  <topichead navtitle="Topic maps">
    <topicref href="map.dita"/>
    <topicref href="bookmap.dita"/>
  </topichead>
  <topicref href="conclusion.dita"/>
</map>

Quelle: DITA for the Impatient

Publications, Collections, Publishing

Beispiele für Publikationen

Dokument
Website
E-book
Help-System

Collections

The term collection is used to describe a potential publication in the DITA source. A ditamap collection is processed to become a publication. In other words, collection describes the source content, while publication describes the output format. A collection is defined in DITA through a ditamap, or multiple embedded ditamaps.

Publication and collection defined

Publishing

The process of transforming DITA source into an output format is known as publishing, processing, or transformation, and the software tools for the process are known as processors, transformers, or publishing engines.

Publication and collection defined

Variable Inhalte

Beispiele: Working with Variable Text in DITA

Spezialisierung

Specialization allows you to define new kinds of information (new structural types or new domains of information), while reusing as much of existing design and code as possible, and minimizing or eliminating the costs of interchange, migration, and maintenance.

What is specialization?

Tutorial: DITA Configuration and Specialization Tutorials

Geschichte

März 2001: IBM stellt Kern-DTD und XML-Schema fertig

Mai 2002: Zur Topic-Spezialisierung kommt die Domain-Spezialisierung

2004 OASIS Technical Commitee

Februar 2005: IBM übergibt das DITA Open Toolkit an Sourceforge

Juni 2005: DITA 1.0

August 2007: DITA 1.1 (neue Bookmap-Spezialisierung)

2010: DITA 1.2 (Lernobjekte)

17.12.2015: DITA 1.3 (Troubleshooting-Topic, Scoped Keys, MathML und Equation-Domains, Relax NG für normative Schemas)

Material: History of DITA | DITA XML.org

Authoring mit Adobe Framemaker

Video Framemaker Basics

Wichtig zum Editieren mit XML

Workspaces
Elementgrenzen
Strukturansicht
Element-Katalog
Pods

Editieren eines Topics vom Typ “Concept”

Erstellen eines Topics vom Typ “Concept”

Editieren des Prologs und der Metadaten eines Topic

Wichtige weitere Punkte

Attributansicht durch Klicken rechts bei Element
Attribut-Pad durch Doppelklicken
Requires attributes
Metadaten zur Audience
Keywords

Erstellen eines Topics vom Typ “Task”

Anwendungen

Optimale Umgebung für DITA

Topic-basierte, modulare Inhalte
Wiederverwendung
Austausch von Inhalten
Übersetzung und Lokalisierung

Sarah O’Keefe: DITA 101 - YouTube

Wichtigste Business Cases

Lokalisierung
Wiederverwendung von Inhalten

Sarah O’Keefe: DITA 101 - YouTube

Herausforderungen für Autoren

Topic-orientiertes Schreiben
Orientierung an wiederverwendbaren Inhalten
Verständnis für technische Hintergründe

Herausforderung für die Organisation

Technische Komplexität
XML-Knowhow in der Organisation
Realisisierung der Potenziale der Inhalte-Wiederverwendung

Component Based Content Management Systems

For the average CCM system, the content is created in smaller-than-page chunks, and assembled, much like a content mashup, to create a larger-sized page for output. A change is made to a component, which can be a single word, phrase, paragraph, or larger, which is then compiled, much like a software “build”, which generates a presentation version of the specified sources. The aggregated content can be pushed out to a Web page, a PDF, or a print destination.

Rahel Bailie: Component content management as content mash-ups

DITA CMSes – DITA Writer

DITA in Firmen

Companies Using DITA – DITA Writer

Beispiele

DITA-Dokumente: dita-community/dita-demo-content-collection: DITA Demonstration Content Collection°°°°°
DITA-basierte Website: The Content Era is here
DITA-basiertes CMS: DITAToo DITA CCMS

Aktuell

Lightweight DITA

LwDITA will provide:

A simplified schema for topics and maps, with fewer elements and tighter content models.
Out of the box mappings and specifications for authoring topics without XML —for example, using HTML5 or Markdown.
A simplified specialization architecture to define new topic types.

Lightweight DITA SC | OASIS

Adobe DITA World

Adobe DITA World 2018 – Home

Lightweight DITA

Lightweight DITAis a simplified version of the Darwin Information Typing Architecture. In comparison to DITA 1.3, LwDITA has a smaller element and attribute set, stricter content models, and a reduced feature set. LwDITA also defines mappings between XML, HTML5, and Markdown.

Beispiel für einen Topic in Markdown


# Installing and Setting up Remote Lighting

Installation of your lighting kit includes installing the light bulbs into light fixtures, preparing the remote control, and programming lighting groups.

## Steps

  1. Install light bulbs.
  2. Prepare remote control.
  3. Program lighting groups.

## Example

 ![Image](remote.png)

Beispiel erweiterter Topic mit YAML Header


 ---
 id: install-and-setup
 author: Kevin Lewis
 ---

# Installing and Setting up Remote Lighting

 Installation of your lighting kit includes installing the light bulbs into light fixtures, preparing the remote control, and programming lighting groups.

 Before you attempt to install your lighting kit, please turn off the power in your electrical circuit panel,

 ## Steps

   1. Install light bulbs.
   2. Prepare remote control.
   3. Program lighting groups.

 ## Example

 The following video demonstrates a recommended installation:

 <video src="remote.mp4" controls poster="remote.png" />

Beispiel für eine Map in Markdown

# Remote Lighting Network

   - [Introduction](introduction.md)
   - [Alternative lighting setups](alternatives.md)
       - [Low power installation](low-power.md)
       - [High power installation](high-power.md)

Material

Lightweight DITA: An Introduction

Markdown DITA syntax reference

Lightweight DITA and DITA 2.0 - DITA Now and in the Future - IXIASOFT

Marking Down DITA · infotexture

Material

Websites:

DITA XML.org is the official community gathering place and information resource for the DITA OASIS Standard, an XML architecture for designing, writing, managing, and publishing information. We encourage you to contribute content to this site.

DITA XML.org | Online community for the Darwin Information Typing Architecture OASIS Standard

Einführungen

DITA 101 webcast - YouTube

data2type GmbH: XML-Technologien | DITA

Code-Beispiele

“Gnostyx” - DITA Demonstration Content Collection

Siehe dazu: ThunderBird: A Sample DITA Documentation Set to Play With – DITA Writer

Videos

List of DITA-related Videos – DITA Writer

Blogs

DITA Writer – Blog, Resource, Interviews and News Relating to DITA XML

Every Page is Page One

Learning DITA Blog

Editoren:

List of DITA Optimized Editors – DITA Writer

Oxygen XML Editor
Xeditor, a CMS editor for XML content | I’d Rather Be Writing
Freie Personal Edition: XMLmind XML Editor: XMLmind DITA Editor

Texte

Step by step process to create new DITA project - Oxygen XML Forum

DITA Maps Manager - Oxygen XML Editor

Reusing DITA Content

10 reasons for moving away from DITA | I’d Rather Be Writing

Tools

XMLmind DITA Converter
DITA Open Toolkit

Gruppen und Listen

DITA Awareness Group: https://www.linkedin.com/groups/162465/ DITA for Small Teams: https://www.linkedin.com/groups/3968768/ DITA Metrics (for effort estimation and ROI calculations): https://www.linkedin.com/groups/2916249/

Sammlung von DITA Links (Heinz Wittenbrink)

Pinboard: bookmarks for heinzwittenbrink tagged ‘dita’

DITA Open Toolkit

Überprüfung Java

Last login: Fri Nov 10 10:47:09 on ttys005
M00087-3:~ heinz$ javac -version
javac 1.8.0_131
M00087-3:~ heinz$

Download

Download DITA-OT

Edit PATH

M00087-3:~ heinz$ echo $PATH
/Users/heinz/DITA/dita-ot-3.0/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin:/Library/TeX/texbin

Check the version

M00087-3:~ heinz$ dita --version
DITA-OT version 3.0
M00087-3:~ heinz$

Erster Test

M00087-3:samples heinz$ dita --input=sequence.ditamap --format=html5 --output=output/sequence
     [xslt] Warning at xsl:stylesheet on line 12 column 59 of map2html5Impl.xsl:
     [xslt]   Stylesheet module plugin:org.dita.html5:xsl/map2html5Impl.xsl is included or imported more
     [xslt]   than once. This is permitted, but may lead to errors or unexpected behavior

Input

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN"
 "../dtd/technicalContent/dtd/map.dtd">
<!-- This file is part of the DITA Open Toolkit project hosted on
     Sourceforge.net. See the accompanying license.txt file for
     applicable licenses.-->
<!-- (C) Copyright IBM Corporation 2001, 2005. All Rights Reserved.
 *-->
<map title="Working in the garage">
<topicref href="tasks/changingtheoil.xml" type="task"></topicref>
<topicref href="tasks/organizing.xml" type="task"></topicref>
<topicref href="tasks/shovellingsnow.xml" type="task"></topicref>
<topicref href="tasks/spraypainting.xml" type="task"></topicref>
<topicref href="tasks/takinggarbage.xml" type="task"></topicref>
<topicref href="tasks/washingthecar.xml" type="task"></topicref>
<topicref href="concepts/lawnmower.xml" type="concept"></topicref>
<topicref href="concepts/oil.xml" type="concept"></topicref>
<topicref href="concepts/paint.xml" type="concept"></topicref>
<topicref href="concepts/shelving.xml" type="concept"></topicref>
<topicref href="concepts/snowshovel.xml" type="concept"></topicref>
<topicref href="concepts/toolbox.xml" type="concept"></topicref>
<topicref href="concepts/tools.xml" type="concept"></topicref>
<topicref href="concepts/waterhose.xml" type="concept"></topicref>
<topicref href="concepts/wheelbarrow.xml" type="concept"></topicref>
<topicref href="concepts/workbench.xml" type="concept"></topicref>
<topicref href="concepts/wwfluid.xml" type="concept"></topicref>
</map>

Exkurs: Output-Erzeugung mit XSL-FO

Apache FOP

Apache(tm) FOP: Quick Start Guide

File:XSL-FO.png - Wikimedia Commons — XSL-FO-Processing

Quelle: File:XSL-FO.png - Wikimedia Commons

URL dieser Präsentation: https://heinzwittenbrink.github.io/slides-intro2dita/
Präsentation auf Github: https://github.com/heinzwittenbrink/slides-intro2dita

Dank an Lief Erickson für wertvollen Input!

Weitere Präsentationen zu DITA

Bedingtes Publizieren mit DITA

Vielen Dank!

heinz at fh-joanneum dot at

DITA-Einführung Heinz Wittenbrink 2020-11-14