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

1,090 views

Published on

The story of where we started, what we bought, and what we are learning as we move from structured FrameMaker using DocBook to Arbortext Editor using DITA.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,090
On SlideShare
0
From Embeds
0
Number of Embeds
482
Actions
Shares
0
Downloads
7
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • MikeLong time Technical WriterIn this implementation I have served as the database architect and technical resource for the rest of the team.JulieSr. technical writer and independent consultant – over 30 years experienceUnstructured word, Ventura Publisher, FrameMakerPersonal DITA user and enthusiastGot the mechanics, working on making reuse possibleAlthough 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.
  • 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.
  • We want to give you a snapshot of our deliverable process, why we could see that something needed to change and our wish list.
  • Tools* Began to “structure with FM-7.1 using free tools and DocBook, self-learning from books, workbooks, online Forums, & FM-Plugins.Advanced to StructuredFrameMaker (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, Mif2GoWebWorks(standard edition)Workflows:* Fm > xml
  • 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.
  • Justification for changing and purchasing toolsets and processes Processes required a checklistTools are fairly difficult to setup and maintainEach writer needs to maintain required toolset and follow the process using the checklist. Hard to setup new writers.Talk about metrics here: Time consuming.
  • 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.
  • 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.
  • 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
  • Building on experienceWe 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.
  • Content analysisWe 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.ResultsStandardize outline: TopicBook
  • Stylesheet building processStylesheets, 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 guideDITA style guide
  • 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.
  • Writers want to control file naming, as in the past. Setup automatic naming rules and forget it.bnamingtheLOOK FOR FILE STRUCTURE that Julie created on the network for her dita workWorking 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.
  • 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.
  • Getting good at searching your contentUnderstand DITA metadata featuresStandardize, “use a taxonomy”Try to learn as you go, not in isoloationeLearning and workingRefer to your Style GuidesRefer to reference booksRefer to peers – discuss
  • Remember your goals: Establish one source of the truth (but don’t force uniformity)Collaboration has to be easyWriters have to be able to iterateMultiple deliverables must be easy to createReview by topic must be easyTopic maintenance must be easy
  • Communicate and compromiseKnow 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 markupConsistent usageUse 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.
  • Look at examples from other DITA docsMentoringForums and other Social Media
  • 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.
  • Mobile accessWeb access
  • What we've developed as "strategies for authoring in DITA"What we're using to help take advantage of the reuse potential of DITAWhat processess (new and old) that we're using to work with DITA authoring
  • 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.
  • Never ends. Each project, always doing it.MindshiftTask orientationBook to topicStay the courseprovide context and acknowledge both problems and success
  • Give us your business card if you would like a ZIP emailed to you with the following:
  • Case Study: Serving Authors' Needs in a Brave New DITA World

    1. 1. Case study: Serving authors’ needs in a brave new DITA world Mike McGinnis Julie Atkins @LavaCon
    2. 2. About the Speakers MJ • Mike McGinnis • Julie Atkins @LavaCon
    3. 3. On the road to DITA J 1. 2. 3. 4. 5. Where we were How we started What we’re learning Where we’re going The biggies and freebies @LavaCon
    4. 4. J Our story… 1 WHERE WE WERE @LavaCon
    5. 5. 1.1 Staff, Content, Tools M • Writers – 2 full-time Tridium writers – 2 contract writers (added ~ 2010) The “Rig” • Content – 80% DocBook – 5% DITA – 20% unstructured • Tools & Workflows – Variety of non-standard tools – Variety of workflows @LavaCon
    6. 6. Tools and Workflows (cont.) M Content Type Tools Process • 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 •FM-7.2 FM > PDF Software Hardware • Installation Guides @LavaCon
    7. 7. 1.2 What we realized M • 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
    8. 8. 1.3 What we planned M • 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
    9. 9. 1.4 What we needed M • 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
    10. 10. J After years of dreaming… 2 HOW WE STARTED @LavaCon
    11. 11. 2.1 What we purchased M • 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
    12. 12. 2.2 Building on experience M • 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
    13. 13. 2.2 Experience (continued) DocBook “Procedure” DITA “Task” @LavaCon
    14. 14. 2.3 Content analysis J • • • • • Driver docs Met weekly with mentors Content analysis Task analysis Results – Reuse potential – Standardized topic list @LavaCon
    15. 15. 2.4 Tech Doc Standards M • Style Sheet development – DITA tagging and highlighting guide – DITA style guide • Code review • Process review @LavaCon
    16. 16. J On the road to DITA… 3 WHAT WE’RE LEARNING @LavaCon
    17. 17. 3.1 Adapting to DITA Environment • File explosion uneasiness • One FrameMaker Chapter is now “many” files @LavaCon M
    18. 18. 3.1 Adapting (continued) M • 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
    19. 19. 3.1 Adapting continued M • 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
    20. 20. 3.2 Content J • 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
    21. 21. 3.3 Content challenges J • Remain task oriented when documenting features • Some features don’t need doc! @LavaCon
    22. 22. 3.3 Standards M • 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
    23. 23. 3.4 Get help M • Use examples to learn to think DITA • Use the experts – Consultants – Forums • Documentation and Technical Writing Management @LavaCon
    24. 24. 3.4 Get help continued M • Read books and refer to them often! @LavaCon
    25. 25. J Briefly… 4 WHERE WE’RE GOING @LavaCon
    26. 26. 4.1 Align docs with agile M • Topics become part of Sprint planning • Reviews become smaller “sprint-friendly” • Engineers are more aware of content development and review @LavaCon
    27. 27. 4.2 Implement doc life cycle M • Take advantage of the CCMS – Workflow – Status – Baselining – Revisioning and archiving • Adapt agile tools (JIRA) to documentation process @LavaCon
    28. 28. 4.3 Alternate content delivery M • Make content available everywhere • Support product branding • Translation @LavaCon
    29. 29. 4.4 Comfort level J • DocBook works in Arbortext Editor • We can get our work done while implementing the new system • Our comfort level is growing @LavaCon
    30. 30. We hope you take away… 5 THE BIGGIES AND FREEBIES @LavaCon
    31. 31. 5.1 The biggies JM • Power of analysis • Mindset shift – Use examples – Talk to each other • Get good help – Single Sourcing Solutions • Stay the course @LavaCon
    32. 32. 5.2 Freebies M • Content analysis spreadsheet • Task analysis interview outline • Links to our best books • A collection of other useful links Email: Julie Atkins @LavaCon

    ×