systems and technology group user technologies © 2005 ibm corporation team authoring using dita and...

Systems and Technology Group User Technologies

© 2005 IBM Corporation

Team Authoring using DITA and ANT

ISTG User Technologies

© 2005 IBM Corporation2 Team Authoring using DITA and ANT March 13, 2005

Agenda

Why do we need team authoring?

What is the authoring environment like?

Who is on the authoring team?

How do we create and assemble topics?

Demonstration (DITA and ANT)



Introduction



Why do we need team authoring?

Old realities: Longer release cycles; isolated information units; fixed delivery format;

Old results: Individual information ownership; isolated, repeated information units; duplicated development efforts; higher deployment costs; lower work efficiency

New challenges: More complex products; shorter release cycles; quicker ID turn-around; flexible delivery formats; need for workload balancing; better work efficiency

New results: Team collaboration; single-sourced, modular, and reusable content; reintegrated info deliverables; reduced development and deployment costs

THEN

NOW



What does the environment look like?

Sourcerepository

Buildingenvironment

(ANT)

Displayenvironment

Authoring environment (DITA XML)



Authoring environment DITA=Darwin Information Typing Architecture

DITA open toolkit– Consists of DTD, XML schema, samples,

documentation

– Provides the infrastructure for topic-based authoring through DTD

XML editor– Key requirements

– User-friendly interface

– XML validation

– Examples

– Arbortext Epic

– Syntex Serna

– BlastRadius XMetaL

– Benefits

– Provides context-appropriate guidance for structured authoring

– Prevents tagging errors

– Improves information quality



Source repository Key requirements

– Command-line access

– Versioning control

– File-filtering capabilities

– Concurrent file-access capabilities

Examples– Content-management systems

– Version-control systems

• IBM Rational® ClearCase®

• IBM CMVC

• Concurrent Version System (CVS)

– Shared file systems

• Network file systems

• Network drives

Benefits– Maintains complete snapshots of files at all times

– Enables retrieval of any old version of a single file

– Allows concurrent authoring and other team collaboration processes

– Allows flexible criteria-based search



Build environment ANT = Another Neat Tool

Key ANT features

– Platform-independent

– Built-in functions and highly extensible

– Declarative rather than procedural specifications of build actions

– Parallel or incremental builds and selective rebuilds

– Eclipse, CM, development and test integration-ready

– Scriptability and advanced build strategies

SW and HW Requirements– Standard workstation with any OS

– Apache ANT

– Java® Software Developer’s Kit (SDK)

– Utilities extensions specific to authoring environment

Benefits– Much easier to use than the Make build manager

– Scheduled, reliable transformations of multiple deliverables in a single process



Display environment

Key features

– Displays all deliverables from a single location

– Simulates what the customer will see

– Can be used by ID, test and development

SW and HW requirements– Standard workstation, any OS

– Web server

– Java Runtime Environment

– Help viewers, such as Eclipse Help, JavaHelp, HTMLHelp, and so on

Benefits– Allows writers to view content changes at any given time

– Allows development and test colleagues to verify requested changes based on defects

– Deploys build results for code integration and product release



Information architects

Writers/Editors

BuildTechnicianTHE

TEAM

Informationarchitect



Information architects

Informationarchitect

Gather and understand user requirements

Define information architecture for all deliverables

Define navigation approach in an information center

Provide guidelines for writers to implement information architecture and navigation approach through DITA topic authoring and DITA map construction

Define style specification for all information deliverables

Define content reuse strategy and provide implementation guidelines



Writers and editors

Construct topic relationships based on navigation design

Work with graphic (artwork) and instructional (eLearning) designers on visual aids for topics

Conduct information reviews

Discover technical information

Author and edit stand-alone, reusable DITA topics according to corporate and other writing guidelines and quality requirements

Assign topic type to all topics

Writers and Editors



Build technicians

Gather ANT build requirements, including hardware and software

Obtain and install necessary hardware and software

Help maintain build environment

Define build actions and targets by customizing ANT scripts

Help debug errors specific to build environment and deliverable transformations

Ensure code deployment for integration and release

Buildtechnician



Creating stand-alone topics from existing sources

Stand-alonetopics

Writing

Typing

Chunking

Repository

Sources

Identify information sources– Existing books

– Product design specifications

– SGML, HTML

Chunk information into topics– Chapters, sections, paragraphs

Assign topic types– Basic types: concept, reference,

task and topic

– Extended types: Message, command, API panel help

Write up individual topics – Stand-alone, article-based and

reusable

– Accessible, MT-readable for globalization

– Conforming to corporate and DITA-specific writing guidelines

– Using a predefined file-naming convention



Assembling deliverables from standalone topics

Determine info requirements for each deliverable

– Gather user requirements

– Perform task analyses

– Determine deliverable format

Prepare source topics– Identify individual topics

– Set up topics for reuse (direct or filtering)

Design info structure via DITA maps

– Define a navigation approach

– Create DITA maps

Define style scheme for presentation

– Presentation requirements

– CSS specifications

DITA Topics(Content)

ANT Build(Transform)

HTML/XHTML

Eclipse HelpJavaHelp

HTMLHelpWebpages

TopicsRepurposed

Reused

DITA Maps(Context)

PDF

BookArticle

BrochureFlyer

ASCII

Text HelpJava Properties

Deliverables(format &

presentation)



Demo

Stand-alone DITA topics and DITA maps

ANT build environment and scripts that specify build actions and targets

Common output format, including HTML/XHTML and PDF



Summary

Changing information development and deployment strategies require closer team collaboration in authoring

The authoring team consists of information architects, writers/editors, and build technicians

The team authoring environment consists of such tool sets as DITA XML, source repositories, ANT build, and content viewers

Information is authored in the form of DITA-compliant topics that are stand-alone and can be reused/repurposed



Web resources DITA XML

– http://xml.coverpages.org/dita.html

– http://groups.yahoo.com/group/dita-users/

– http://www.oasis-open.org/committees/dita

– http://sourceforge.net/projects/dita-ot/

– http://www-106.ibm.com/developerworks/xml/library/x-dita1/index.html

– http://www-128.ibm.com/developerworks/xml/library/x-dita6/x-dita_downloads.html

Ant – http://www.ant.apache.org

Eclipse– http://www.eclipse.org

Java JDK– http://www-128.ibm.com/developerworks/java/jdk/

– http://java.sun.com/j2se/



Web resources (continued) IBM Information Centers

– http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

XML Editors

– Arbortext Epic http://www.arbortext.com/html/epic_editor_overview.html

– Syntex Serna http://www.syntext.com/products/serna/

– BlastRadius XMetaL http://www.xmetal.com/



Notices

Copyright © 2005 by International Business Machines Corporation.

No part of this document may be reproduced or transmitted in any form without written permission from IBM Corporation.

References in this document to IBM products, programs, or services does not imply that IBM intends to make such such products, programs or services available in all countries in which IBM operates or does business. Any reference to an IBM Program Product in this document is not intended to state or imply that only that program product may be used. Any functionally equivalent program, that does not infringe IBM’s intellectually property rights, may be used instead. It is the user’s responsibility to evaluate and verify the operation of any on-IBM product, program or service.

The information provided in this document is distributed "AS IS" without any warranty, either express or implied. IBM EXPRESSLY DISCLAIMS any warranties of merchantability, fitness for a particular purpose OR NONINFRINGEMENT.

IBM, the IBM logo and TotalStorage are registered trademarks of IBM Corporation.

systems and technology group user technologies © 2005 ibm corporation team authoring using dita and...

Documents