Serving authorsneeds
â˘
0 gostouâ˘232 visualizaçþes
Case study: Serving authors' needs in a brave new DITA world
Recomendados
Recomendados
Mais conteĂşdo relacionado
Destaque
Semelhante a Serving authorsneeds
Semelhante a Serving authorsneeds (20)
Ăltimo
Ăltimo (20)
Serving authorsneeds
- 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.) @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
- 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 outline @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â ⢠Try to learn as you go, not in isoloation @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 @LavaCon J M
- 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
Notas do Editor
- 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: