serving authorsneeds
DESCRIPTION
Case study: Serving authors' needs in a brave new DITA worldTRANSCRIPT
![Page 1: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/1.jpg)
@LavaCon
Case study:Serving authors’ needs
in a brave new DITA worldMike McGinnis
Julie Atkins
![Page 3: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/3.jpg)
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
![Page 4: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/4.jpg)
1 WHERE WE WEREOur story…
@LavaCon
J
![Page 5: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/5.jpg)
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
![Page 6: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/6.jpg)
Tools and Workflows (cont.)
@Hashtag @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
![Page 7: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/7.jpg)
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
![Page 8: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/8.jpg)
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
![Page 9: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/9.jpg)
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
![Page 10: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/10.jpg)
2 HOW WE STARTEDAfter years of dreaming…
@LavaCon
J
![Page 11: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/11.jpg)
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
![Page 12: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/12.jpg)
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
![Page 13: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/13.jpg)
2.2 Experience (continued)
@LavaCon
DocBook “Procedure”
DITA “Task”
![Page 14: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/14.jpg)
2.3 Content analysis
• Driver docs• Met weekly with mentors• Content analysis• Task analysis• Results
– Reuse potential– Standardized outline
@LavaCon
J
![Page 15: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/15.jpg)
2.4 Tech Doc Standards
• Style Sheet development– DITA tagging and highlighting guide– DITA style guide
• Code review• Process review
@LavaCon
M
![Page 16: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/16.jpg)
3 WHAT WE’RE LEARNINGOn the road to DITA…
@LavaCon
J
![Page 17: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/17.jpg)
File explosion
3.1 Adapting to DITA Environment
• File explosion uneasiness• One FrameMaker Chapter
is now “many” files
@LavaCon
M
![Page 18: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/18.jpg)
File explosion
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
![Page 19: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/19.jpg)
3.1 Adapting continued
• Getting good at searching your content”• Try to learn as you go, not in isoloation
@LavaCon
M
![Page 20: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/20.jpg)
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
@LavaCon
J M
![Page 21: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/21.jpg)
3.3 Content challenges
• Remain task oriented when documenting features
• Some features don’t need doc!
@LavaCon
J
![Page 22: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/22.jpg)
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
![Page 23: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/23.jpg)
3.4 Get help
• Use examples to learn to think DITA
• Use the experts– Consultants– Forums
• Documentation and Technical Writing Management
@LavaCon
M
![Page 24: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/24.jpg)
3.4 Get help continued
• Read books and refer to them often!
@LavaCon
M
![Page 25: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/25.jpg)
4 WHERE WE’RE GOINGBriefly…
@LavaCon
J
![Page 26: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/26.jpg)
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
![Page 27: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/27.jpg)
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
![Page 28: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/28.jpg)
4.3 Alternate content delivery
• Make content available everywhere• Support product branding• Translation
@LavaCon
M
![Page 29: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/29.jpg)
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
![Page 30: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/30.jpg)
5 THE BIGGIES AND FREEBIES
We hope you take away…
@LavaCon
![Page 31: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/31.jpg)
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
![Page 32: Serving authorsneeds](https://reader033.vdocuments.site/reader033/viewer/2022051513/545c130cb1af9f4b0a8b462f/html5/thumbnails/32.jpg)
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