1. Systems and Technology Group User Technologies © 2005 IBM Corporation Team Authoring using DITA and ANT

2. ISTG User Technologies © 2005 IBM Corporation 2Team Authoring using DITA and ANTMarch 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)

3. ISTG User Technologies © 2005 IBM Corporation 3Team Authoring using DITA and ANTMarch 13, 2005 Introduction

4. ISTG User Technologies © 2005 IBM Corporation 4Team Authoring using DITA and ANTMarch 13, 2005 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

5. ISTG User Technologies © 2005 IBM Corporation 5Team Authoring using DITA and ANTMarch 13, 2005 What does the environment look like? Source repository Building environment (ANT) Display environment Authoring environment (DITA XML)

6. ISTG User Technologies © 2005 IBM Corporation 6Team Authoring using DITA and ANTMarch 13, 2005 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

7. ISTG User Technologies © 2005 IBM Corporation 7Team Authoring using DITA and ANTMarch 13, 2005 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

8. ISTG User Technologies © 2005 IBM Corporation 8Team Authoring using DITA and ANTMarch 13, 2005 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

9. ISTG User Technologies © 2005 IBM Corporation 9Team Authoring using DITA and ANTMarch 13, 2005 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

10. ISTG User Technologies © 2005 IBM Corporation 10Team Authoring using DITA and ANTMarch 13, 2005 Information architects Writers/Editors Build Technician THE TEAM Information architect

11. ISTG User Technologies © 2005 IBM Corporation 11Team Authoring using DITA and ANTMarch 13, 2005 Information architects Information architect  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

12. ISTG User Technologies © 2005 IBM Corporation 12Team Authoring using DITA and ANTMarch 13, 2005 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

13. ISTG User Technologies © 2005 IBM Corporation 13Team Authoring using DITA and ANTMarch 13, 2005 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 Build technician

14. ISTG User Technologies © 2005 IBM Corporation 14Team Authoring using DITA and ANTMarch 13, 2005 Creating stand-alone topics from existing sources Stand-alone topics 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

15. ISTG User Technologies © 2005 IBM Corporation 15Team Authoring using DITA and ANTMarch 13, 2005 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 Help JavaHelp HTML Help Webpages Topics Repurposed Reused DITA Maps (Context) PDF Book Article Brochure Flyer ASCII Text Help Java Properties Deliverables (format & presentation)

16. ISTG User Technologies © 2005 IBM Corporation 16Team Authoring using DITA and ANTMarch 13, 2005 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

17. ISTG User Technologies © 2005 IBM Corporation 17Team Authoring using DITA and ANTMarch 13, 2005 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

18. ISTG User Technologies © 2005 IBM Corporation 18Team Authoring using DITA and ANTMarch 13, 2005 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/

19. ISTG User Technologies © 2005 IBM Corporation 19Team Authoring using DITA and ANTMarch 13, 2005 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/

20. ISTG User Technologies © 2005 IBM Corporation 20Team Authoring using DITA and ANTMarch 13, 2005 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.

21. Systems and Technology Group User Technologies © 2005 IBM Corporation