ºÝºÝߣ

Editor's Notes

• #3: 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 ¨C 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.
• #4: 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.
• #5: We want to give you a snapshot of our deliverable process, why we could see that something needed to change and our wish list.
• #6: 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
• #7: 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.
• #8: 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.
• #9: 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.
• #11: 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.
• #12: 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
• #13: 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.
• #15: 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
• #16: 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
• #17: 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.
• #18: 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.
• #19: 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.
• #20: 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 ¨C discuss
• #21: 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
• #23: 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.
• #24: Look at examples from other DITA docsMentoringForums and other Social Media
• #26: 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.
• #29: Mobile accessWeb access
• #30: 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
• #31: 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.
• #32: Never ends. Each project, always doing it.MindshiftTask orientationBook to topicStay the courseprovide context and acknowledge both problems and success
• #33: Give us your business card if you would like a ZIP emailed to you with the following: