ImplementingDITA™ Setting the stage: Creating simple DITA projects that will scale up Anna van Raaphorst Richard H. (Dick) Johnson Authors of the DITA

implementingDITA™

Setting the stage:Creating simple DITA projects that will scale up

Anna van RaaphorstRichard H. (Dick) JohnsonAuthors of the DITA Open Toolkit User Guide

VR Communications, Inc.www.vrcommunications.com

Revised: March 29, 2007

http://www.vrcommunications.com/

March 2007 implementingDITA™: Setting the Stage 2

Contents

• Two DITA projects: “simple” and “complex”

• Key messages and themes: Creating scalable DITA projects

• Simple project details

• Complex project details

• TinyWeb demo server

• Lessons learned

• For more information

Key Messages and Themes

Creating scalable DITA projects


Key Messages

Increased complexity can result in both:

- A significant increase in benefits

- A significant increase in challenges

Take the time to architect and plan well at the

simple stage, so your more complex projects are

“elegantly sophisticated,”

not

“a complex mess of spaghetti-docs.”


Themes: Architecture and Content

• Benefits of complexity: sophistication!– Higher quality content– Opportunities for content reuse, collaboration,

and customization– Opportunities for content integration and

reuse (for example, documentation and training material)

• Challenges of complexity– Need for tight, centralized control and close

collaboration


Themes: Technology, Logistics

• Benefits of complexity: sophistication!– Faster response time– Tighter integration with product and related software

(e.g., translation memory)– Ultimately cheaper

• Challenges of complexity– Technical complexity can increase beyond a typical

writer’s comprehension– Potential loss of control of the process and tool choice– Significant start-up costs (time and $)

Simple Project

DITA Open Toolkit User Guide


Doc Ant build script

XML source file(messages content)

XSLT stylesheetfor “dynamic” DITAsource file

XHTML, HTML Help, PDF output

Static DITA source files(all other content)

“Dynamic” DITA source files(messages content)

Source

DITA source

Content output

Xalan orSAXON

SimpleProject

2 Disconnected Processes

DITA Open Toolkit

1i 1i

1p

1o

2p

2i

2p

2o

2i

i = inputp = processo = output

Command-line script

1p


Simple Project• Overview

– Title: DITA Open Toolkit User Guide– Collaborative effort: Anna van Raaphorst (content specialist) and

Dick Johnson (technology specialist)– Volunteer contribution to the DITA community

• Document profile– Bookmap specialization (demo level)– 20 chapters– 300 topics– Publishing targets: XHTML, HTML Help, PDF

• Publishing history– August 2006 (Toolkit 1.2.2)– October 2006 (Toolkit 1.3.0)– (Planned) Early April 2007 (Toolkit 1.3.1)


Simple Project (continued)• Contents

– Basic concepts– Getting started– Getting information– Evaluating DITA and DITA Open Toolkit– DITA use cases– Installing, upgrading– Plug-ins– Setting up your working environment– Processing and publishing to all 9 target environments– Troubleshooting the build process– Creating topics and maps, sample files– Linking, accessing, reusing, customizing, specializing, localizing (translating),

managing, distributing, migrating– Sample files– FAQs– Release information– DITA core vocabulary (controlled vocabulary, glossary)


Simple Project (continued)

• Changes/additions to April 2007 edition– Significant restructuring– Basic concepts– Localization (translation)– Content reuse– Building from within Eclipse– Building Eclipse Information Centers– Eclipse XMLBuddy editor– Processing overview– Publishing to XHTML using a frameset


Simple Project (continued)• Features, benefits

– “Vanilla” DITA– Core vocabulary

• Defines the project and product (Toolkit)• Content reuse

– Sample projects and processing scripts• Grocery shopping• Garage

– PHP-based tools for debugging and reporting (available free)

– Dynamic generation of Toolkit messages files– Advice based on collaborative, real-world experience


Simple Project (continued)

• Challenges– Content organization, architecture– Technical learning curve– Collaboration

• With subject-matter experts• Among team members

– Content integrity (establishing, maintaining)– Strategic thinking and planning (today’s

solution must scale up to tomorrow’s!)

Simple Project Set-up


Directory Structure (overview)

Toolkit, User Guide,and sample files

User Guide output files

Output files produced byPHP debugging and reporting tools


Directory Structure (source)

continued

continued


Debugging and Reporting Tools


“Conditionalization”


Core Vocabulary (reuse)

Complex Project

Set of documents built within the product


Complex Project: Product

• Skytide Analytical Platform (www.skytide.com)• OLAP tool: “Enables the analysis of

nonrelational data using traditional Business Intelligence techniques without requiring transformation of the data into relational format”

• XML-based (written in Java)• Consists of Designer, Server, and SDK• Works with DB2 9 (Viper)• Can do business analytics and content analytics

http://www.skytide.com/


Complex Project: Documentation

• Titles– Getting Started (GS)– Administration Guide (AG)– Modeling Guide (MG)– Future: Developer Guide (DG)

• Formal content reuse– Common files conref’ed between topics– Installation instructions (GS and AG)– Images (All)– Glossary (core vocabulary) (All)– Introduction (doc descriptions, target audience) (All)– Object properties (All)


Complex Project: Doc (continued)

• Target publishing environments– XHTML– PDF– JavaDoc reference material– Future: Context-sensitive help (on object properties)

• Specialization: Bookmap• Customization (ditaval)

– Windows/UNIX– PDF/non-PDF


Complex Project: Doc (continued)

• Processing reuse– Three-tier build process: (1) product build.xml (2)

generic doc build.xml (3) separate Ant script for each doc

– Can build a complete release package (including docs) any time

– Doc “unit test” takes place outside the top-level product build

• Informal content reuse – Shared content between documentation and training

material – Estimated savings: 50-75%, 2 days to formalize 2-day

training class


Product files:(1) .class files (a) properties repository (array of strings) (b) other class files(2) .jar file

Main Ant build script (build.xml)

Doc Ant build script(doc/build.xml)

XML source file(properties content)

Java source file(s)

XSLT stylesheets- For dynamic Java

source file- For dynamic DITA

file

Java compiler

JavaDoc output(properties)

XHTML outputPDF output(properties, other)

Static DITA source files(all other content)

Dynamic DITA source files(properties content)

Used 3 times:

(A) JavaDoc (B) Props repository(C) dita2xhtml, dita2pdf

Source

DITA source

Content output

Xalan orSAXON

DITA OT

B

A C

JDoc compiler

ComplexProject

5 Sequential Processes

1i 1i1o

2p

2o

3p

3i

4i

3o

1-5p

4o

1&4p

5p

5p

5o

1i

2i4i

5i

5i



Directory Structure

TinyWeb Server Details and Demo

Created to illustrate the complex project


TinyWeb Server

• Product: Very simple web server that displays photos of Australia and NZ

• Documentation– Input: XML file of error messages– Output (1): Product error messages displayed when

runtime errors occur– Output (2): JavaDoc– Output (3): Dynamic DITA file that is merged with

static DITA files to produce XHTML output


TinyWeb product files:(1) .class files (a) messages repository (array of strings) (b) other class files(2) .jar file

Main Ant build script (build.xml)

Doc Ant build script(doc/build.xml)

XML source file(properties content) Java source file(s)

Java compiler

XHTML output(messages, other)

Static DITA source files (all other content)

Dynamic DITA source files(messages content)

Source

DITA source

Content output

DITA OT

TinyWebProject


XSLT stylesheets- For dynamic Java

source file- For dynamic DITA

file

1 2

See directory structure(next slide)

JavaDoc output(messages)

JDoc compiler

3

4

5

5

67

8


Directory Structure

Directory Contentsbin Java compiler output filesbuild Product .jar filesdoc DITA source/output files, Ant scriptjavadoc JavaDoc outputmaster_ant_scripts Master Ant build scriptsrc Java source fileswebsite_test Sample website for project serverxml Project metadata filexsl XSLT stylesheets (DITA, Java code)

12

3

4

5

6

7

8

See diagram (prior slide)


XML Message Definitions


Dynamic Java Source


Dynamic DITA Source


Generated PDF Output


Generated JavaDoc


Server Startup Messages


Server Log Messages

Lessons Learned

The importance of “setting the stage”


Lessons Learned• Do at least two simple prototypes before tackling a complex project• First prototype (3-4 weeks)

– All new content (concepts, tasks, reference topics)– At least 2 output targets– 2 tiers– Up to 50 topics – 1-3 people (one being an information architect and one who is

technology savvy)• Second prototype (6-8 weeks)

– Some new, and some migrated content – Focus on reuse, customization, specialization, linking strategies – 3 tiers – Up to 100+ topics– 4-6 people (one architect, one technologist, one editor)


Lessons Learned (continued)

• Apply the lessons learned doing your simple projects to set the stage for your subsequent complex projects

• Enjoy your future successes!


For More Information

Anna and Dick’s professional website:www.vrcommunications.com

DITA Open Toolkit User Guide:www.vrcommunications.com/resourcesOr:http://dita-ot.sourceforge.net/SourceForgeFiles/doc/user_guide.html

These slides and TinyWeb server package:www.vrcommunications.com/resources

We welcome comments and suggestions!


http://www.vrcommunications.com/resources

http://dita-ot.sourceforge.net/SourceForgeFiles/doc/user_guide.html

http://www.vrcommunications.com/resources

implementingDITA™

Setting the stage:Creating simple DITA projects that will scale up

(Last Slide)

VR Communications, Inc.www.vrcommunications.com


Documents

ImplementingDITA™ Setting the stage: Creating simple DITA projects that will scale up Anna van Raaphorst Richard H. (Dick) Johnson Authors of the DITA