systems and technology group user technologies © 2005 ibm corporation team authoring using dita and...
TRANSCRIPT
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)
ISTG User Technologies
© 2005 IBM Corporation3 Team Authoring using DITA and ANT March 13, 2005
Introduction
ISTG User Technologies
© 2005 IBM Corporation4 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation5 Team Authoring using DITA and ANT March 13, 2005
What does the environment look like?
Sourcerepository
Buildingenvironment
(ANT)
Displayenvironment
Authoring environment (DITA XML)
ISTG User Technologies
© 2005 IBM Corporation6 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation7 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation8 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation9 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation10 Team Authoring using DITA and ANT March 13, 2005
Information architects
Writers/Editors
BuildTechnicianTHE
TEAM
Informationarchitect
ISTG User Technologies
© 2005 IBM Corporation11 Team Authoring using DITA and ANT March 13, 2005
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
ISTG User Technologies
© 2005 IBM Corporation12 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation13 Team Authoring using DITA and ANT March 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
Buildtechnician
ISTG User Technologies
© 2005 IBM Corporation14 Team Authoring using DITA and ANT March 13, 2005
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
ISTG User Technologies
© 2005 IBM Corporation15 Team Authoring using DITA and ANT March 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 HelpJavaHelp
HTMLHelpWebpages
TopicsRepurposed
Reused
DITA Maps(Context)
BookArticle
BrochureFlyer
ASCII
Text HelpJava Properties
Deliverables(format &
presentation)
ISTG User Technologies
© 2005 IBM Corporation16 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation17 Team Authoring using DITA and ANT March 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
ISTG User Technologies
© 2005 IBM Corporation18 Team Authoring using DITA and ANT March 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/
ISTG User Technologies
© 2005 IBM Corporation19 Team Authoring using DITA and ANT March 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/
ISTG User Technologies
© 2005 IBM Corporation20 Team Authoring using DITA and ANT March 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.