State of the Art in Technical Communication Part I ... · Structured Authoring Technical Control Writing for reuse (self-contained) Enforcement of (XML-)structure by tools (Structure)

State of the Art

in Technical Communication

Part I:

Methods for Structured Authoring

Prof. Dr. Wolfgang Ziegler

Karlsruhe University of Applied Sciences

Communication & Media Management

Institute for Information and Content Management

(I4ICM)

© Prof. Dr. Wolfgang Ziegler

CV

1987-1997 Theoretical Physics (Ph.D.), Würzburg Univ., Germany

1997 Tech. Doc Services (CCMS Consultant, Developer XML/XSLT)

2003 Professor of Information & Content Management

(Karlsruhe Univ. Appl. Sciences)

Independent CCMS consultant (system evaluation & introduction)

Research Transfer: I4ICM Institute for Information and Content Management

(REx, PI-Class, PI-Mod, Content-Delivery)


Overview Part I

Introduction

Modularization

Meta-Data

Information Structures & XML

Building Documents

Language Support

Cross Media Publishing


Introduction


Organization and Information

Tech Com.

Department

Develop.

Sales/Marketing

Engineering/Manufact.

Product

InformationPre-Sales After-Sales

… the black box


Information in the Product Lifecycle

TrainingManufact.R & D Service Sales

ERP

Data

CAD-Drawings

Models

Partslists

Require

ments

Speci-

fication

Sales-

Doc.

Configu-

rator

Hazard

analysis

Developer

Service

info

Tech. Desc.

Certificates

Tests

Supplier

Doc.

Service-

Reports

Cust.

Feedback

Product

Catalog

Data-

sheets

Service-

info &

Manual

Machine

Info

System

User

Manual

Help

Desk

InfoTraining

Doc.

CBT/WBT

Plann.

Install.

Mount.

Doc.

Spare

Part

Catalog

(Web)-

Portals

e-Business

PIM

Product Information Management

CM

Content Management

Standards

Patents

Regul. Doc.

SPIM


Evolution of Re-Use

Uncontrolled Reuse = Document Copies

??


Evolution of Re-Use (Single Sourcing)

Controlled Reuse =

Referencing Modular Topics

(Single Sourcing)

Single Sourcing


(Automization)


Standardization levels

Content / Language (Writing Rules, Terminology)

Structure (Semantics) + Granularity (Modules/Topics)

Format (Data format), Media

Layout


Modular authoring and reuse


Modular Authoring

Goal

Decrease document creation time & effort by re-use of content

(„modules“, „topics“, „chunks“, „objects“)

Methods

Definition of Modular Content

Modular writing and metadata enrichment of modules

Standardized authoring using (XML-) structures, writing guidelines

and language control

Aggregation of documents by reuse of (large number of) modules


Estimating the Reuse Potential

Module Matrix: Analyzing and defining reusable content

Doc. 1

Mod. 1

Mod. 2

Mod. 3 Var. a

Doc. 2

Mod. 1

Mod. 3 Var. b

Doc. 3

Mod. 1

Mod. 2

Doc. 4

Mod. 1

Mod. 2

Mod. 3 Var. c


flexibility

higher reusability

Balance of granularity

Modul size

simplicity

lower reusability

redundancy

complexity


Bottom-up Analysis: Module Matrix

Class Doc 1 Doc 2 Doc 3

Chap

1.1

task Mod 1

(S)

Mod 1

(S)

Mod 1

(S)

Chap

1.2.1

descr. Mod 2a

(V)

Mod 2b

(V)

Mod 2c

(V)

Chap

1.2.2

diag-

nosysMod 3

(O)

document

structure

doc./prod. variants, media, target group Rockley 2003 („Content Audit“)

Drewer /Ziegler 2010


Requirements to modular topics

Self-contained

Addressable

Uniqueness

Referable

Exchangeable

Reusable

Plannable

Structered


32,927,3

51,6

8,5

30,2

43,746,6

43,6

9,6

0

20

40

60

%

DOG 2000

tekom 2005

tekom 2008

tekom 2013

Primary Modules

Variant

Management

Distributrion and Concept of Module Sizes


Metadata


Modules and Metadata?


Metadata examples


Metadata systematics

„life cycle“

„intrinsic

properties“

„extrinsic

properties“

(use)

„Product classification“ „Information classification“

author („John May“)

version („4.0“)

procedure type („removal“)

info.type („operation“)

mod.type („task“)component („seat“)

functional part („ head restraint“)

valid ( “A“, “B“)

series („169“, „245“)pub.type („online“)

doc.type („owner‘s manual“)

status („released“) translation status („in work“)

language („de“)

product („passenger car“)


(PI-)Classification of Modular Topics

Addressable modular content

Uniquely identified by metadata (classification)

Product-classification applicable and recommended for all

component-based products

Information-classification helpful for all types of modular content

Structures depend often on information classes


Estimating the Reuse Potential


Dok. 1

Mod. 1

Mod. 2

Mod. 3 Var. a

Dok. 2

Mod. 1

Mod. 3 Var. b

Dok. 3

Mod. 1

Mod. 2

Dok. 4

Mod. 1

Mod. 2

Mod. 3 Var. c


Classification of Modules

Module Matrix: Planning use of CCMS using e.g. PI-Classification

Mod. 1

Mod. 2

Mod. 3 Var. a

Mod. 1

Mod. 3 Var. b

Mod. 1

Mod. 2

Mod. 1

Mod. 2

Mod. 3 Var. c


Practical classification (module matrix)

3-level intrinsic

product classes

3-level intrinsic

information classesKoenig&Bauer,

Printing machines


File system: folder structure

Use of intrinsic metadadata for classification and retrieval

Using extrinsic metadata as folders

often makes it difficult

to store topics

File storage and Classification of modular topics

seat

head restraint

removal

Product A

Product B

unique

ambiguous


Information Structures & XML


Standardization (content + structure)

<?xml version="1.0" encoding="UTF-8"?>

<task>

<heading> </heading>

<step> </step>

<step> <menue> </menue></step>

<step> </step>

<result> </result>

</task>

Displaying structure nodes

The selected nodes are displayed in a separate window.

Open file by using code editor.

Fill-in XPATH-expression.

Activate menue entry „evaluate“.

Rules-based authoring; enforced by editing tools and terminology/language control


Information Structures (within modular topics)

Information models

Usually XML-based:

Document Type Definition (DTD), Extensible Schema Definition (XSD)

Guide authors through predefined structures

Help to control structures by tools (parser)

Semantic structures help to control writing guidelines

Can depend on information classes (information typing)

Improves usability and readability of content due to structural

consistency of information (recognition scheme)


Information Models: Standard(ized) Structures

2

113

Docbook

DITA

S1000D

project/customer

specific

structureCMS

specific

structure

standardized

structure

PI-Mod


Logical structure definition (Example: PI-Mod)


Logical structure definition (Example: DITA)


DITA

Information model released by IBM and donated as open-source

software (structure definition) to OASIS 2004

Origin in software documentation

Standard mechanisms to specialize/customize structures

Adaptions (specializations) to other domains (learning content,

semiconductor industries, …)

Pre-defined information types (topic, task, reference, concept)

Topic based reuse mechanism (DITA-map) to aggregate topics

Publishing toolset (open toolkit)

Built-in application in editing tools


https://www.youtube.com/watch?v=NO5xRs9fTig

Examples of editing tools: Adobe FrameMaker


Examples of editing tools: JustSystems XMetaL


Building Documents


Building documents (Single Sourcing)

Document Structure (trees, maps) Modular Topics

Re-use by reference


92,1%

70,0%

56,8%

52,9%

51,3%

38,1%

36,2%

34,9%

34,0%

33,3%

18,8%

12,5%

User Manual

Installation Manual

Service Manual

Software Description

Operation Manual

Data sheets

Training Material

Repair Manual

Spare Part Catalogue

Online-Help

Parts lists

Pricing Catalogues

Cross Chanel Publishing (After-Sales Document Types)

Reuse accross

document types

requires explicit

revision management


4%

7%

13%

15% 15%

13% 13%12%

5%

2%1%

0%

2%

4%

6%

8%

10%

12%

14%

16%

1 2 3 4 5 6 7 8 9 10 11

Cross Channel Publishing

Number of published information products68 %: 4 - 8 Information Products

Information product (doc. types)


DITA Map (FrameMaker)


DITA Map (XMetaL)


Document Filtering (general method)

Filtering of Master-Documents

(collections of variants) by metadata

Filter can be used to exclude:

modular topics (e.g. DITA: topic references

containing validities)

submodular elements (conditional content / content

references)

Desktop Publishing: Conditional Text


Document Filtering

Doc. (Master)

1

2(Var. a)

2 (Var. b)

2 (Var. c)

3

4

5 (Var. a)

5 (Var. b)

5 (Var. c)

Doc. 1

12 (Var.a)

3

4 5 (Var.a)F: a

F: b

F: c

Dok. c

1

2 (Var.1b)

3

4 5 (Var.b)

Dok. c

12 (Var.c)

3

4 5 (Var.c)


Language Support


Structured Authoring

Technical Control

Writing for reuse (self-contained)

Enforcement of (XML-)structure by tools

(Structure) Rules apply to all languages

(Specific) Language control by tools

Quality Control and Enhancement

Consistency in terms and phrases (authoring guidelines)

Reusing controlled content


Language control

Writing guidelines &

terminology enforced

Combination with XML

structure of information

model (context)


Estimating the Reuse Potential: Source Language


Dok. 1

Mod. 1

Mod. 2

Mod. 3 Var. a

Dok. 2

Mod. 1

Mod. 3 Var. b

Dok. 3

Mod. 1

Mod. 2

Dok. 4

Mod. 1

Mod. 2

Mod. 3 Var. c


Reuse in Target Language

Reduction of Translation Volume & Costs

Doc. 1

Mod. 1

Mod. 2

Mod. 3 Var. a

Doc. 2

Mod. 1

Mod. 3 Var. b

Doc. 3

Mod. 1

Mod. 2

Doc. 4

Mod. 1

Mod. 2

Mod. 3 Var. c




XML-driven Publication

Rules-based mapping from structure to layout

Rules can be defined for:

• target groups

• media

• Infotype/document type

• localization

• personalization

Structure elements

Layout elements

automated

or

manually

controlled

Rules


Cross Media Publishing 2013

Parallel publishing of three media/formats (avg)

74,1%

73,7%

72,6%

35,9%

25,3%

17,2%

13,7%

11,7%

5,6%

3,9%

3,2%

0,9%

0,1%

Print-Dokument

pdf.-Dokument (print)

pdf.-Dokument (online)

Online-Hilfen (HTML-Help, Java-Help etc.)

CD Anwendungen

HTML-Dokumente

Webseiten (serverbasiert)

Präsentationsunterlagen

Multimedia-Dokumentation

eLearning-Anwendungen

App

eBook

HöranleitungAudio

eLearning

Multimedia Documentation

Presentations

Web (server based)

HTML Documents

CD Applications

Online Help


5%

25%

29%

19%

11%

6%4%

2%

0%

5%

10%

15%

20%

25%

30%

35%

1 Medium 2 Medien 3 Medien 4 Medien 5 Medien 6 Medien 7 Medien mehr als 7 Medien

Published media

23 %: more than 4 media

70 %: more than 2 media


XML

XSLT (XML) XML

HTML

PDF


XSL-FO

CHM

processor

processor

hh

DTP

epub

Adobe Framemaker,

InDesign, MS Word

Exchange, Migration, …

../../VDMA_111007/DEMO/mod1.xml

../../VDMA_111007/DEMO/mod1.xml


Doc.js

Rendering of HTML Documents

Doc.xsl

XSLTProzessor

Doc.htmMOD.xml

Doc_h.css

MOD.xml

Doc_x.css


Rendering of PDF Documents (XSL-FO)

Doc.xsl

XSLTProzessor

Doc.fo

XSLFOProzessor

Doc.pdf

Doc.xml

../../../Vorlesung/Print/Dokument.pdf

../../../Vorlesung/Print/Dokument.pdf


Automized Desktop Publishing (Word, FrameMaker, InDesign)

Doc.xsl

XSLTProcessor

Doc_WordML.xml

Doc.pdf

Doc.xml


A summary to be continued … (lets have a break)

Build (primary) modules which are reusable, identifyable and self-

contained

Open question: How long will a file-system based solution meet

your demands?

Part II: CCMS

CCMS drivers

Process Support