SlideShare ist ein Scribd-Unternehmen logo
1 von 32
Downloaden Sie, um offline zu lesen
@LavaCon
Case study:
Serving authors’ needs
in a brave new DITA world
Mike McGinnis
Julie Atkins
@LavaCon
About the Speakers
• Mike McGinnis
• Julie Atkins
MJ
On the road to DITA
1. Where we were
2. How we started
3. What we’re learning
4. Where we’re going
5. The biggies and freebies
@LavaCon
J
1 WHERE WE WERE
Our story…
@LavaCon
J
The “Rig”
1.1 Staff, Content, Tools
• Writers
– 2 full-time Tridium writers
– 2 contract writers (added ~ 2010)
• Content
– 80% DocBook
– 5% DITA
– 20% unstructured
• Tools & Workflows
– Variety of non-standard tools
– Variety of workflows
@LavaCon
M
Tools and Workflows (cont.)
@LavaCon
Content Type Tools Process
Software
• NiagaraAX-3.x •FrameMaker 7.2, 8, 9, 10
•DocBook stylesheets (docbook-xsl-1.71.1 customized)
•Saxon processor
•Custom xsl processing as part of the s/w build
•DITA OT (another rig?)
FM > XML > HTML
• Appliance Guides •FrameMaker
•WebWorks
•InsetPlus (FM plugin)
•AXCM (FM plugin)
FM > HTML
• Other (Developer) •Word, Acrobat Pro
•Dreamweaver (CSS &HTML editing)
•Acrobat Pro
•Word > PDF
•HTML >PDF
Hardware
• Installation Guides •FM-7.2 FM > PDF
M
1.2 What we realized
• Problems ahead
– More Writers
– Mixed Toolsets
– Mixed Processes
• Justification for change
– Avoid disaster
– Take advantage of new technologies (DITA)
– Increase productivity
– Scalable for future growth
@LavaCon
M
1.3 What we planned
• New Tech Pubs processes
– Make DITA the Tridium standard
– Move to task-based documentation
– Learn to use minimalism principles
– Content inventory and analysis
• New Tech Pubs tools
– Standardized
– Scalable
– DITA compatible
@LavaCon
M
1.4 What we needed
• Education and training
– Make DITA the Tridium standard
– Move to task-based documentation
– Learn to use minimalism principles
• Help from an expert(s)
– Choosing tools
– Installing and configuring CCMS
– Performing content inventory and analysis
• Meet ongoing documentation deadlines
@LavaCon
M
2 HOW WE STARTED
After years of dreaming…
@LavaCon
J
2.1 What we purchased
• Mentoring from Single Sourcing Solutions
– Purchasing, spec’ing process
– Installation
– “Jump Start” process
• Arbortext Tools from PTC
– Arbortext Editor
– Arbortext Styler
– Arbortext Publishing Engine
– Arbortext Content Manager
• Arbortext eLearning Library
@LavaCon
M
2.2 Building on experience
• We already know “structured”
– DITA “Topics” similar to DocBook <Sections>
– DITA “Tasks” are like DocBook <Procedures>
• DITA is different but draw on familiar
concepts
– XML markup
– Non XML markup (format catalogs/styles)
• FM users and styles
• Word users and styles
@LavaCon
M
2.2 Experience (continued)
@LavaCon
DocBook
“Procedure”
DITA “Task”
2.3 Content analysis
• Driver docs
• Met weekly with mentors
• Content analysis
• Task analysis
• Results
– Reuse potential
– Standardized topic list
@LavaCon
J
2.4 Tech Doc Standards
• Style Sheet development
– DITA tagging and highlighting guide
– DITA style guide
• Code review
• Process review
@LavaCon
M
3 WHAT WE’RE LEARNING
On the road to DITA…
@LavaCon
J
3.1 Adapting to DITA
Environment
• File explosion uneasiness
• One FrameMaker Chapter
is now “many” files
@LavaCon
M
3.1 Adapting (continued)
• Tool helps and hindrances
• Trusting CCMS not file naming conventions
• Configure CCMS to help with your workflow
• Possible tool confusion with new interface and tool
legacy terminology (not for writers)
• DITA helps and hindrances
• DITA Maps can help
• DITA Maps can hurt
• Learn how to use your new tools – discuss
with the group regularly
@LavaCon
M
3.1 Adapting continued
• Getting good at searching your content
– Understand DITA metadata features
– Standardize, “use a taxonomy”
• Learn as you go, not in isolation
– eLearning and working
– Refer to your Style Guides
– Refer to reference books
– Refer to peers – discuss
@LavaCon
M
3.2 Content
• Have a strategy for legacy content
• Know your subject
• Standardize topic/book outline
– One task per topic; no subtasks
– Install, configure, test
• Develop consistent naming conventions
• Use throw-away DITAmaps
@LavaCon
J
3.3 Content challenges
• Remain task oriented when documenting
features
• Some features don’t need doc!
@LavaCon
J
3.3 Standards
• Communicate and compromise
– Writing style and element (tag) usage
– Process
– Content (reuse opportunities)
• Review markup and usage
– Consistent markup enables reuse
– Taking advantage of reuse opportunities
@LavaCon
M
3.4 Get help
• Use examples to learn to think DITA
• Use the experts
– Consultants
– Forums
• Documentation and Technical Writing
Management
@LavaCon
M
3.4 Get help continued
• Read books and refer to them often!
@LavaCon
M
4 WHERE WE’RE GOING
Briefly…
@LavaCon
J
4.1 Align docs with agile
• Topics become part of Sprint planning
• Reviews become smaller “sprint-friendly”
• Engineers are more aware of content
development and review
@LavaCon
M
4.2 Implement doc life cycle
• Take advantage of the CCMS
– Workflow
– Status
– Baselining
– Revisioning and archiving
• Adapt agile tools (JIRA) to documentation
process
@LavaCon
M
4.3 Alternate content delivery
• Make content available everywhere
• Support product branding
• Translation
@LavaCon
M
4.4 Comfort level
@LavaCon
J
• DocBook works in Arbortext Editor
• We can get our work done while
implementing the new system
• Our comfort level is growing
5 THE BIGGIES AND
FREEBIES
We hope you take away…
@LavaCon
5.1 The biggies
• Power of analysis
• Mindset shift
– Use examples
– Talk to each other
• Get good help
– Single Sourcing Solutions
• Stay the course
@LavaCon
J M
5.2 Freebies
• Content analysis spreadsheet
• Task analysis interview outline
• Links to our best books
• A collection of other useful links
Email: Julie Atkins
@LavaCon
M

Weitere ähnliche Inhalte

Was ist angesagt?

Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...
Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...
Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...Alexander Berman
 
The agile elephant in the room
The agile elephant in the roomThe agile elephant in the room
The agile elephant in the roomAgileDenver
 
Lean Canvas for Internal Product Owners
Lean Canvas for Internal Product OwnersLean Canvas for Internal Product Owners
Lean Canvas for Internal Product OwnersKeith Klundt
 
Structuring for Content Reuse with MadCap Doc-To-Help
Structuring for Content Reuse with MadCap Doc-To-HelpStructuring for Content Reuse with MadCap Doc-To-Help
Structuring for Content Reuse with MadCap Doc-To-HelpMary Connor
 
Documentation in the Agile Space
Documentation in the Agile SpaceDocumentation in the Agile Space
Documentation in the Agile SpaceAbel Lineberger
 
Maintainable Machine Learning Products
Maintainable Machine Learning ProductsMaintainable Machine Learning Products
Maintainable Machine Learning ProductsAndrew Musselman
 
It's gonna be PowerApps and Flow - are you ready?
It's gonna be PowerApps and Flow - are you ready? It's gonna be PowerApps and Flow - are you ready?
It's gonna be PowerApps and Flow - are you ready? Penny Coventry
 
Managing your Content Projects with Success and Panache
Managing your Content Projects with Success and PanacheManaging your Content Projects with Success and Panache
Managing your Content Projects with Success and PanacheAhava Leibtag
 
Unbabel: Translation as a Service by Vasco Pedro (Unbabel)
Unbabel: Translation as a Service by Vasco Pedro (Unbabel)Unbabel: Translation as a Service by Vasco Pedro (Unbabel)
Unbabel: Translation as a Service by Vasco Pedro (Unbabel)TAUS - The Language Data Network
 

Was ist angesagt? (11)

Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...
Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...
Multiple Formats, One Source: Supporting Multi-Format Publishing with a Singl...
 
The agile elephant in the room
The agile elephant in the roomThe agile elephant in the room
The agile elephant in the room
 
Lean Canvas for Internal Product Owners
Lean Canvas for Internal Product OwnersLean Canvas for Internal Product Owners
Lean Canvas for Internal Product Owners
 
Structuring for Content Reuse with MadCap Doc-To-Help
Structuring for Content Reuse with MadCap Doc-To-HelpStructuring for Content Reuse with MadCap Doc-To-Help
Structuring for Content Reuse with MadCap Doc-To-Help
 
Documentation in the Agile Space
Documentation in the Agile SpaceDocumentation in the Agile Space
Documentation in the Agile Space
 
Dev ops in real life
Dev ops in real lifeDev ops in real life
Dev ops in real life
 
Maintainable Machine Learning Products
Maintainable Machine Learning ProductsMaintainable Machine Learning Products
Maintainable Machine Learning Products
 
It's gonna be PowerApps and Flow - are you ready?
It's gonna be PowerApps and Flow - are you ready? It's gonna be PowerApps and Flow - are you ready?
It's gonna be PowerApps and Flow - are you ready?
 
Managing your Content Projects with Success and Panache
Managing your Content Projects with Success and PanacheManaging your Content Projects with Success and Panache
Managing your Content Projects with Success and Panache
 
Core conv
Core convCore conv
Core conv
 
Unbabel: Translation as a Service by Vasco Pedro (Unbabel)
Unbabel: Translation as a Service by Vasco Pedro (Unbabel)Unbabel: Translation as a Service by Vasco Pedro (Unbabel)
Unbabel: Translation as a Service by Vasco Pedro (Unbabel)
 

Andere mochten auch

Driving DITA off the Map
Driving DITA off the MapDriving DITA off the Map
Driving DITA off the MapJang F.M. Graat
 
Two to Tango - Agile Meets DITA
Two to Tango - Agile Meets DITATwo to Tango - Agile Meets DITA
Two to Tango - Agile Meets DITANabayan Roy
 
Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...
Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...
Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...IXIASOFT
 
Beyond the Book and the Class: Using DITA for Training & Support
Beyond the Book and the Class: Using DITA for Training & SupportBeyond the Book and the Class: Using DITA for Training & Support
Beyond the Book and the Class: Using DITA for Training & SupportLasselle-Ramsay
 
The DITA Learning and Training Specialization
The DITA Learning and Training SpecializationThe DITA Learning and Training Specialization
The DITA Learning and Training SpecializationIXIASOFT
 
English Parts Of Speech
English Parts Of SpeechEnglish Parts Of Speech
English Parts Of Speechguesta684c8b
 

Andere mochten auch (8)

Developing dita maps
Developing dita mapsDeveloping dita maps
Developing dita maps
 
Driving DITA off the Map
Driving DITA off the MapDriving DITA off the Map
Driving DITA off the Map
 
Two to Tango - Agile Meets DITA
Two to Tango - Agile Meets DITATwo to Tango - Agile Meets DITA
Two to Tango - Agile Meets DITA
 
Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...
Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...
Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descrip...
 
Beyond the Book and the Class: Using DITA for Training & Support
Beyond the Book and the Class: Using DITA for Training & SupportBeyond the Book and the Class: Using DITA for Training & Support
Beyond the Book and the Class: Using DITA for Training & Support
 
The DITA Learning and Training Specialization
The DITA Learning and Training SpecializationThe DITA Learning and Training Specialization
The DITA Learning and Training Specialization
 
Brain Anatomy
Brain AnatomyBrain Anatomy
Brain Anatomy
 
English Parts Of Speech
English Parts Of SpeechEnglish Parts Of Speech
English Parts Of Speech
 

Ähnlich wie Case Study: Serving Authors' Needs in a Brave New DITA World

Serving authorsneeds
Serving authorsneedsServing authorsneeds
Serving authorsneedsJulie Atkins
 
Lucene BootCamp
Lucene BootCampLucene BootCamp
Lucene BootCampGokulD
 
Islandora Webinar: Building a Repository Roadmap
Islandora Webinar: Building a Repository RoadmapIslandora Webinar: Building a Repository Roadmap
Islandora Webinar: Building a Repository Roadmapeohallor
 
DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016
DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016
DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016IXIASOFT
 
Day in the life of a data librarian [presentation for ANU 23Things group]
Day in the life of a data librarian [presentation for ANU 23Things group]Day in the life of a data librarian [presentation for ANU 23Things group]
Day in the life of a data librarian [presentation for ANU 23Things group]Jane Frazier
 
Agile Content Development and the IXIASOFT DITA CMS
Agile Content Development and the IXIASOFT DITA CMSAgile Content Development and the IXIASOFT DITA CMS
Agile Content Development and the IXIASOFT DITA CMSIXIASOFT
 
Markup languages and warp-speed documentation
Markup languages and warp-speed documentationMarkup languages and warp-speed documentation
Markup languages and warp-speed documentationLois Patterson
 
Lois Patterson: Markup Languages and Warp-Speed Documentation
Lois Patterson:  Markup Languages and Warp-Speed DocumentationLois Patterson:  Markup Languages and Warp-Speed Documentation
Lois Patterson: Markup Languages and Warp-Speed DocumentationJack Molisani
 
Digitization revealed (2018 NLA Annual Conference)
Digitization revealed (2018 NLA Annual Conference)Digitization revealed (2018 NLA Annual Conference)
Digitization revealed (2018 NLA Annual Conference)Marina Georgieva
 
Getting Started With Omeka (DHSI 2015 Unconference)
Getting Started With Omeka (DHSI 2015 Unconference)Getting Started With Omeka (DHSI 2015 Unconference)
Getting Started With Omeka (DHSI 2015 Unconference)jkmcgrath
 
Building an LDA topic model using Wikipedia
Building an LDA topic model using WikipediaBuilding an LDA topic model using Wikipedia
Building an LDA topic model using WikipediaSharon Garewal
 
“Filling the digital preservation gap” an update from the Jisc Research Data ...
“Filling the digital preservation gap”an update from the Jisc Research Data ...“Filling the digital preservation gap”an update from the Jisc Research Data ...
“Filling the digital preservation gap” an update from the Jisc Research Data ...Jenny Mitcham
 
Digital Library Project.pdf
Digital Library Project.pdfDigital Library Project.pdf
Digital Library Project.pdfTuji Yusuf
 
Reengineering PDF-Based Documents Targeting Complex Software Specifications
Reengineering PDF-Based Documents Targeting Complex Software SpecificationsReengineering PDF-Based Documents Targeting Complex Software Specifications
Reengineering PDF-Based Documents Targeting Complex Software SpecificationsMoutasm Tamimi
 
Experience Converting from Ruby to Scala
Experience Converting from Ruby to ScalaExperience Converting from Ruby to Scala
Experience Converting from Ruby to ScalaJohn Nestor
 
HASTAC Scholars: Omeka and Digital Archives
HASTAC Scholars: Omeka and Digital ArchivesHASTAC Scholars: Omeka and Digital Archives
HASTAC Scholars: Omeka and Digital Archivesjkmcgrath
 
Cooperative Cataloging Projects: Managing Them for Best Results
Cooperative Cataloging Projects: Managing Them for Best ResultsCooperative Cataloging Projects: Managing Them for Best Results
Cooperative Cataloging Projects: Managing Them for Best ResultsNASIG
 

Ähnlich wie Case Study: Serving Authors' Needs in a Brave New DITA World (20)

Serving authorsneeds
Serving authorsneedsServing authorsneeds
Serving authorsneeds
 
Lucene BootCamp
Lucene BootCampLucene BootCamp
Lucene BootCamp
 
Islandora Webinar: Building a Repository Roadmap
Islandora Webinar: Building a Repository RoadmapIslandora Webinar: Building a Repository Roadmap
Islandora Webinar: Building a Repository Roadmap
 
DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016
DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016
DITA Surprise, Unwrapping DITA Best Practices - tekom tcworld 2016
 
Day in the life of a data librarian [presentation for ANU 23Things group]
Day in the life of a data librarian [presentation for ANU 23Things group]Day in the life of a data librarian [presentation for ANU 23Things group]
Day in the life of a data librarian [presentation for ANU 23Things group]
 
Agile Content Development and the IXIASOFT DITA CMS
Agile Content Development and the IXIASOFT DITA CMSAgile Content Development and the IXIASOFT DITA CMS
Agile Content Development and the IXIASOFT DITA CMS
 
Markup languages and warp-speed documentation
Markup languages and warp-speed documentationMarkup languages and warp-speed documentation
Markup languages and warp-speed documentation
 
Lois Patterson: Markup Languages and Warp-Speed Documentation
Lois Patterson:  Markup Languages and Warp-Speed DocumentationLois Patterson:  Markup Languages and Warp-Speed Documentation
Lois Patterson: Markup Languages and Warp-Speed Documentation
 
394 wade word2007-ssp2008
394 wade word2007-ssp2008394 wade word2007-ssp2008
394 wade word2007-ssp2008
 
Digitization revealed (2018 NLA Annual Conference)
Digitization revealed (2018 NLA Annual Conference)Digitization revealed (2018 NLA Annual Conference)
Digitization revealed (2018 NLA Annual Conference)
 
Getting Started With Omeka (DHSI 2015 Unconference)
Getting Started With Omeka (DHSI 2015 Unconference)Getting Started With Omeka (DHSI 2015 Unconference)
Getting Started With Omeka (DHSI 2015 Unconference)
 
Xm lforthe smallerpublisher-andywilliams
Xm lforthe smallerpublisher-andywilliamsXm lforthe smallerpublisher-andywilliams
Xm lforthe smallerpublisher-andywilliams
 
Building an LDA topic model using Wikipedia
Building an LDA topic model using WikipediaBuilding an LDA topic model using Wikipedia
Building an LDA topic model using Wikipedia
 
“Filling the digital preservation gap” an update from the Jisc Research Data ...
“Filling the digital preservation gap”an update from the Jisc Research Data ...“Filling the digital preservation gap”an update from the Jisc Research Data ...
“Filling the digital preservation gap” an update from the Jisc Research Data ...
 
Digital Library Project.pdf
Digital Library Project.pdfDigital Library Project.pdf
Digital Library Project.pdf
 
Reengineering PDF-Based Documents Targeting Complex Software Specifications
Reengineering PDF-Based Documents Targeting Complex Software SpecificationsReengineering PDF-Based Documents Targeting Complex Software Specifications
Reengineering PDF-Based Documents Targeting Complex Software Specifications
 
Experience Converting from Ruby to Scala
Experience Converting from Ruby to ScalaExperience Converting from Ruby to Scala
Experience Converting from Ruby to Scala
 
HASTAC Scholars: Omeka and Digital Archives
HASTAC Scholars: Omeka and Digital ArchivesHASTAC Scholars: Omeka and Digital Archives
HASTAC Scholars: Omeka and Digital Archives
 
Cooperative Cataloging Projects: Managing Them for Best Results
Cooperative Cataloging Projects: Managing Them for Best ResultsCooperative Cataloging Projects: Managing Them for Best Results
Cooperative Cataloging Projects: Managing Them for Best Results
 
Webcast: DITA Best Practices
Webcast: DITA Best PracticesWebcast: DITA Best Practices
Webcast: DITA Best Practices
 

Kürzlich hochgeladen

9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding TeamAdam Moalla
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXTarek Kalaji
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024SkyPlanner
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfinfogdgmi
 
AI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity WebinarAI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity WebinarPrecisely
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintMahmoud Rabie
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1DianaGray10
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfJamie (Taka) Wang
 
Nanopower In Semiconductor Industry.pdf
Nanopower  In Semiconductor Industry.pdfNanopower  In Semiconductor Industry.pdf
Nanopower In Semiconductor Industry.pdfPedro Manuel
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPathCommunity
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1DianaGray10
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsSafe Software
 
20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-pyJamie (Taka) Wang
 
Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Adtran
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesMd Hossain Ali
 
UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8DianaGray10
 

Kürzlich hochgeladen (20)

9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBX
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024Salesforce Miami User Group Event - 1st Quarter 2024
Salesforce Miami User Group Event - 1st Quarter 2024
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdf
 
AI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity WebinarAI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity Webinar
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership Blueprint
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
 
Nanopower In Semiconductor Industry.pdf
Nanopower  In Semiconductor Industry.pdfNanopower  In Semiconductor Industry.pdf
Nanopower In Semiconductor Industry.pdf
 
20150722 - AGV
20150722 - AGV20150722 - AGV
20150722 - AGV
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation Developers
 
20230104 - machine vision
20230104 - machine vision20230104 - machine vision
20230104 - machine vision
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
 
20230202 - Introduction to tis-py
20230202 - Introduction to tis-py20230202 - Introduction to tis-py
20230202 - Introduction to tis-py
 
Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
 
201610817 - edge part1
201610817 - edge part1201610817 - edge part1
201610817 - edge part1
 
UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8UiPath Studio Web workshop series - Day 8
UiPath Studio Web workshop series - Day 8
 

Case Study: Serving Authors' Needs in a Brave New DITA World

  • 1. @LavaCon Case study: Serving authors’ needs in a brave new DITA world Mike McGinnis Julie Atkins
  • 2. @LavaCon About the Speakers • Mike McGinnis • Julie Atkins MJ
  • 3. On the road to DITA 1. Where we were 2. How we started 3. What we’re learning 4. Where we’re going 5. The biggies and freebies @LavaCon J
  • 4. 1 WHERE WE WERE Our story… @LavaCon J
  • 5. The “Rig” 1.1 Staff, Content, Tools • Writers – 2 full-time Tridium writers – 2 contract writers (added ~ 2010) • Content – 80% DocBook – 5% DITA – 20% unstructured • Tools & Workflows – Variety of non-standard tools – Variety of workflows @LavaCon M
  • 6. Tools and Workflows (cont.) @LavaCon Content Type Tools Process Software • NiagaraAX-3.x •FrameMaker 7.2, 8, 9, 10 •DocBook stylesheets (docbook-xsl-1.71.1 customized) •Saxon processor •Custom xsl processing as part of the s/w build •DITA OT (another rig?) FM > XML > HTML • Appliance Guides •FrameMaker •WebWorks •InsetPlus (FM plugin) •AXCM (FM plugin) FM > HTML • Other (Developer) •Word, Acrobat Pro •Dreamweaver (CSS &HTML editing) •Acrobat Pro •Word > PDF •HTML >PDF Hardware • Installation Guides •FM-7.2 FM > PDF M
  • 7. 1.2 What we realized • Problems ahead – More Writers – Mixed Toolsets – Mixed Processes • Justification for change – Avoid disaster – Take advantage of new technologies (DITA) – Increase productivity – Scalable for future growth @LavaCon M
  • 8. 1.3 What we planned • New Tech Pubs processes – Make DITA the Tridium standard – Move to task-based documentation – Learn to use minimalism principles – Content inventory and analysis • New Tech Pubs tools – Standardized – Scalable – DITA compatible @LavaCon M
  • 9. 1.4 What we needed • Education and training – Make DITA the Tridium standard – Move to task-based documentation – Learn to use minimalism principles • Help from an expert(s) – Choosing tools – Installing and configuring CCMS – Performing content inventory and analysis • Meet ongoing documentation deadlines @LavaCon M
  • 10. 2 HOW WE STARTED After years of dreaming… @LavaCon J
  • 11. 2.1 What we purchased • Mentoring from Single Sourcing Solutions – Purchasing, spec’ing process – Installation – “Jump Start” process • Arbortext Tools from PTC – Arbortext Editor – Arbortext Styler – Arbortext Publishing Engine – Arbortext Content Manager • Arbortext eLearning Library @LavaCon M
  • 12. 2.2 Building on experience • We already know “structured” – DITA “Topics” similar to DocBook <Sections> – DITA “Tasks” are like DocBook <Procedures> • DITA is different but draw on familiar concepts – XML markup – Non XML markup (format catalogs/styles) • FM users and styles • Word users and styles @LavaCon M
  • 14. 2.3 Content analysis • Driver docs • Met weekly with mentors • Content analysis • Task analysis • Results – Reuse potential – Standardized topic list @LavaCon J
  • 15. 2.4 Tech Doc Standards • Style Sheet development – DITA tagging and highlighting guide – DITA style guide • Code review • Process review @LavaCon M
  • 16. 3 WHAT WE’RE LEARNING On the road to DITA… @LavaCon J
  • 17. 3.1 Adapting to DITA Environment • File explosion uneasiness • One FrameMaker Chapter is now “many” files @LavaCon M
  • 18. 3.1 Adapting (continued) • Tool helps and hindrances • Trusting CCMS not file naming conventions • Configure CCMS to help with your workflow • Possible tool confusion with new interface and tool legacy terminology (not for writers) • DITA helps and hindrances • DITA Maps can help • DITA Maps can hurt • Learn how to use your new tools – discuss with the group regularly @LavaCon M
  • 19. 3.1 Adapting continued • Getting good at searching your content – Understand DITA metadata features – Standardize, “use a taxonomy” • Learn as you go, not in isolation – eLearning and working – Refer to your Style Guides – Refer to reference books – Refer to peers – discuss @LavaCon M
  • 20. 3.2 Content • Have a strategy for legacy content • Know your subject • Standardize topic/book outline – One task per topic; no subtasks – Install, configure, test • Develop consistent naming conventions • Use throw-away DITAmaps @LavaCon J
  • 21. 3.3 Content challenges • Remain task oriented when documenting features • Some features don’t need doc! @LavaCon J
  • 22. 3.3 Standards • Communicate and compromise – Writing style and element (tag) usage – Process – Content (reuse opportunities) • Review markup and usage – Consistent markup enables reuse – Taking advantage of reuse opportunities @LavaCon M
  • 23. 3.4 Get help • Use examples to learn to think DITA • Use the experts – Consultants – Forums • Documentation and Technical Writing Management @LavaCon M
  • 24. 3.4 Get help continued • Read books and refer to them often! @LavaCon M
  • 25. 4 WHERE WE’RE GOING Briefly… @LavaCon J
  • 26. 4.1 Align docs with agile • Topics become part of Sprint planning • Reviews become smaller “sprint-friendly” • Engineers are more aware of content development and review @LavaCon M
  • 27. 4.2 Implement doc life cycle • Take advantage of the CCMS – Workflow – Status – Baselining – Revisioning and archiving • Adapt agile tools (JIRA) to documentation process @LavaCon M
  • 28. 4.3 Alternate content delivery • Make content available everywhere • Support product branding • Translation @LavaCon M
  • 29. 4.4 Comfort level @LavaCon J • DocBook works in Arbortext Editor • We can get our work done while implementing the new system • Our comfort level is growing
  • 30. 5 THE BIGGIES AND FREEBIES We hope you take away… @LavaCon
  • 31. 5.1 The biggies • Power of analysis • Mindset shift – Use examples – Talk to each other • Get good help – Single Sourcing Solutions • Stay the course @LavaCon J M
  • 32. 5.2 Freebies • Content analysis spreadsheet • Task analysis interview outline • Links to our best books • A collection of other useful links Email: Julie Atkins @LavaCon M

Hinweis der Redaktion

  1. Mike Long time Technical Writer In this implementation I have served as the database architect and technical resource for the rest of the team. Julie Sr. technical writer and independent consultant – over 30 years experience Unstructured word, Ventura Publisher, FrameMaker Personal DITA user and enthusiast Got the mechanics, working on making reuse possible Although I am a consultant coming in from the outside with some DITA experience, I have been working as a writer team member and an advocate for all things DITA.
  2. We’re telling our story. We’re not there yet, but we’ve made great progress and trust that something we say will encourage you with practical experience and advice on your journey. If you have questions, please make a note and we will leave time at the end to engage your questions.
  3. We want to give you a snapshot of our deliverable process, why we could see that something needed to change and our wish list.
  4. Tools * Began to “structure with FM-7.1 using free tools and DocBook, self-learning from books, workbooks, online Forums, & FM-Plugins. Advanced to Structured FrameMaker (7.2, 9, 10) all tricked out with plugins for “conrefs” and “insets” DocBook: DocBook stylesheets (xsl), Saxon processor, Ant (see the whole list in Joanne Hackos DITA book) WebWorks (standard edition) DITA: DITA-FMx, InsetPlus and other West Street Consulting tools, Archiving tool, Mif2Go WebWorks (standard edition) Workflows: * Fm > xml
  5. The significance of this list is not simply recognizing the confusion and file sharing limitations imposed by the different toolsets. It is realizing the amount of support is required for setting up the tools and maintaining a suffiicient level of expertise with the tool so that you can troubleshoot and make changes as necessary over the years. This is especially hard if you don’t tweak them that often.
  6. Justification for changing and purchasing toolsets and processes Processes required a checklist Tools are fairly difficult to setup and maintain Each writer needs to maintain required toolset and follow the process using the checklist. Hard to setup new writers. Talk about metrics here: Time consuming.
  7. Standardized tools that are: * sustainable * scalable with growth I know that some people are using files systems or non-cms based tools to support DITA. For me that was not an attractive option.
  8. We have spent years analyzing our situation and attending conferences. Just as a practical matter, we think you would like to know what we bought, how we have leveraged our experience to change our ways of doing things, how we analyzed our content, and how we prepared to build our style sheets.
  9. SSS Worked with us through the specification and purchasing process to help us buy the software that we needed and not buy what we didn’t need. Some sales people may sell the software but they really don’t know the software. Needs vary by organization
  10. Building on experience We started with Structured Authoring and DocBook. "Book Structure" was an easier introduction to Structured Writing than DITA but provided to be a great intro into XML and structured authoring in general. We'd been doing that for 5 years or more. This also provided experience with the structured authoring tools... Using docbook, we’ve been writing in “topics” for years. While not perfect, they do give us a great transition point for moving to DITA concepts, references, and tasks.
  11. Content analysis We followed analyzed a subset of our doc library (driver documents), finding opportunities for shared content. We got a sample analysis spreadsheet from our Mentors and adapted it. The result of the analysis step was a list of topics that seemed to be standard for all drivers. Just as it is important to standardize your use of elements, it helps (for reuse) to standardize your outline. One of us took the new list of topics and applied them to writing a new driver guide. Each week we met with our mentors and discussed the experience and what we were learning. Results Standardize outline: Topic Book
  12. Stylesheet building process Stylesheets, process documentation references, and examples available for Writers as they use new tools and methods. (we are using a Confluence Site and Windchill folder to hold these docs). DITA tagging and highlighting guide DITA style guide
  13. We are learning things about our new tools, and about how to work with content as we move toward a full DITA implementation. We are learning the importance of standards and how to enforce them. And we recognize the need for help from our external consultants.
  14. Writers want to control file naming, as in the past. Setup automatic naming rules and forget it. bnaming theLOOK FOR FILE STRUCTURE that Julie created on the network for her dita work Working in our "legacy" FrameMaker environment, all files are stored on a local hard drive and backed up to a network drive or on our Portal. This issue was addressed (not "solved") immediately by installing and learning to use a CCMS. Working with a CMS was a bit confusing at first: Difference between an XML editor and a CMMS repository database. Need to understand the new model of storing in database versus filesystem. While the structure of the content stored in the CMS appeared to be similar to a familiar HDD file structure, a major difference is the concept of a container that is separate from the document. This confusion demonstrated itself when we created a topic, then wanted to change the name of the topic file. A CMS provides a history of the topic life cycle. Containers can include metadata. It became clear that we have a whole new way to look at data.
  15. Writers want to control file naming, as in the past. Setup automatic naming rules and forget it. Working in our "legacy" FrameMaker environment, all files are stored on a local hard drive and backed up to a network drive or on our Portal. This issue was addressed (not "solved") immediately by installing and learning to use a CCMS. Working with a CMS was a bit confusing at first: Difference between an XML editor and a CMMS repository database. Need to understand the new model of storing in database versus filesystem. While the structure of the content stored in the CMS appeared to be similar to a familiar HDD file structure, a major difference is the concept of a container that is separate from the document. This confusion demonstrated itself when we created a topic, then wanted to change the name of the topic file. A CMS provides a history of the topic life cycle. Containers can include metadata. It became clear that we have a whole new way to look at data.
  16. Getting good at searching your content Understand DITA metadata features Standardize, “use a taxonomy” Try to learn as you go, not in isoloation eLearning and working Refer to your Style Guides Refer to reference books Refer to peers – discuss
  17. Remember your goals: Establish one source of the truth (but don’t force uniformity) Collaboration has to be easy Writers have to be able to iterate Multiple deliverables must be easy to create Review by topic must be easy Topic maintenance must be easy
  18. Communicate and compromise Know what you’re standards are. Talk about them, change them if needed. Example: “dialog box” vs. “dialog” Make sure everyone is using the same process. Identify and share reuse possibilities (task analysis, documentation plan identifies) Review markup Consistent usage Use of tags <shortdesc>, <prereq>, task wording, such as use of gerund. Example: “Definition List” vs <ul> Document how you do it and check that you doing how you documented it.
  19. Look at examples from other DITA docs Mentoring Forums and other Social Media
  20. Many company product development processes are changing. We need to change with them. Our tools possess capabilities that we have explored but not implemented yet. The possibilities seem endless. Beyond the constant striving for more, we seek to reach a comfort zone where we won’t be constantly implementing new stuff.
  21. Mobile access Web access
  22. What we've developed as "strategies for authoring in DITA" What we're using to help take advantage of the reuse potential of DITA What processess (new and old) that we're using to work with DITA authoring
  23. We want you to take home some specific ideas that we trust will help you. We would also like to make available some specific resources.
  24. Never ends. Each project, always doing it. Mindshift Task orientation Book to topic Stay the course provide context and acknowledge both problems and success
  25. Give us your business card if you would like a ZIP emailed to you with the following: