Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.

Going the DITA way

484 visualizaciones

Publicado el

DITA (Darwin Information Typing Architecture) is an open standard that has evolved over the years and is evolving with time. Many organizations are keen to adopt DITA but have a lot of legacy documentation and are unsure of how to manage that while transitioning to a new paradigm.

This presentation describes the pre-requisites of migrating to DITA, planning tips, effort estimation guidelines, training requirements, and some do’s and don’ts.
- Learn to assess legacy documentation
- Understand how to create a strategy for migration to DITA
- Get acquainted with the training plan for migration
- Know the steps to migrate to DITA
- Know the hurdles and how to handle those

This presentation was given by Abigail Samuel and Alka Acharya, both information developers at IBM, at the STC India Annual Conference in 2013.
http://goa2013.stc-india.org/program/#going-dita
http://goa2013.stc-india.org/speakers/

Abigail Samuel has spent over two decades in the publishing and technical communication industry, specializing in information development, DITA, instructional design, and e-learning. She has lead a team of information developers for two products, who successfully migrated legacy documentation to DITA.

Alka Acharya has a total IT experience of over ten years with technical communication experience of over eight years. She led a team who have successfully migrated projects to DITA at IBM.

Publicado en: Software
  • Sé el primero en comentar

Going the DITA way

  1. 1. 10/16/2013 © 2013 IBM Corporation Going the way . . . Abigail Samuel and Alka Acharya Information Developers @ IBM
  2. 2. Going the DITA way . . . 2 © 2013 IBM Corporation
  3. 3. Going the DITA way . . . 3 © 2013 IBM Corporation
  4. 4. Going the DITA way . . . 4 © 2013 IBM Corporation
  5. 5. Going the DITA way . . . 5 © 2013 IBM Corporation
  6. 6. Going the DITA way . . . 6 © 2013 IBM Corporation Problems with legacy documentation model  Book paradigm  Linear flow  Bulky, difficult to manage  Information duplication  …  In short, problems for end users as well as the documentation teams.
  7. 7. Going the DITA way . . . 7 © 2013 IBM Corporation Legacy documentation at IBM  A document markup language based on Standard Generalized Markup Language (SGML).  The legacy documentation followed the book paradigm.
  8. 8. Going the DITA way . . . 8 © 2013 IBM Corporation IBM invented DITA  Developed the information typing strategy  Implemented the strategy by using XML and was named DITA!
  9. 9. Going the DITA way . . . 9 © 2013 IBM Corporation DITA – As we know it Darwin Information Typing Architecture
  10. 10. Going the DITA way . . . 10 © 2013 IBM Corporation The DITA solution  Create, manage, and publish XML-based information  Topic-oriented paradigm  Flexible content structuring  Facilitate reuseEclipse ArchitectureMapBuildMapsTopicsOutputsEclipse helpJavaHelpHTMLHelpWeb pagesBooks & PDFsLearningWriteBuildArchitectInformation ArchitectureMapBuildMapsTopicsOutputsWriteBuildArchitectInformation ArchitectureMapBuildMapsTopicsOutputs
  11. 11. Going the DITA way . . . 11 © 2013 IBM Corporation DITA – As we experienced it Dynamic Influential Trendsetter Adaptive
  12. 12. Going the DITA way . . . 12 © 2013 IBM Corporation Interesting Read! Source: http://www.ditawriter.com/so-whos-using-dita-january-2013-update 2
  13. 13. Going the DITA way . . . 13 © 2013 IBM Corporation Adopting DITA Conceptualize and decide – Create a business case and justifications, proof of concept (POC) – Thought leaders get the buy-in from top management
  14. 14. Going the DITA way . . . 14 © 2013 IBM Corporation Moving to DITA Initiate the change 1. Investigate tools and processes 2. Launch pilot project 3. Define the migration strategy 4. Announce, demo, educate, advocate, and support DITA OT – HTML to DITA Mif2Go Adobe FrameMaker Conversion Tables Stilo Migrate Proprietary tools …
  15. 15. Going the DITA way . . . 15 © 2013 IBM Corporation Our need for migration  Some of the existing legacy information sets of our projects were still in the SGML based format  Corporate directive, deadlines set
  16. 16. Going the DITA way . . . 16 © 2013 IBM Corporation The DITA migration process ASSESS DECIDE PROTOTYPE PLAN TRAIN EXECUTE MONITOR
  17. 17. Going the DITA way . . . 17 © 2013 IBM Corporation Assess legacy content
  18. 18. Going the DITA way . . . 18 © 2013 IBM Corporation Assess legacy content INFORMATION UNIT It could be any modular unit of information, but in the context of this presentation, we refer to it as piece of information that can be completed end-to- end, translated, and published as a unit without other dependencies.
  19. 19. Going the DITA way . . . 19 © 2013 IBM Corporation Assess legacy content Use a consistent metric throughout for sizing
  20. 20. Going the DITA way . . . 20 © 2013 IBM Corporation Assess legacy content Online documentation Downloadable PDFs Context-sensitive help Embedded help Technical notes . . .
  21. 21. Going the DITA way . . . 21 © 2013 IBM Corporation Assess legacy content Other documentation Error messages Code, Javadocs, MAN pages Other departments . . .
  22. 22. Going the DITA way . . . 22 © 2013 IBM Corporation Assess legacy content Other departments or products that might have dependencies on this documentation set
  23. 23. Going the DITA way . . . 23 © 2013 IBM Corporation Assess legacy content All legacy content? Only certain kinds of information? Only content that will continue to be updated in the future? Examples: GUI-based installation steps will change entirely Support discontinued for ABC operating system
  24. 24. Going the DITA way . . . 24 © 2013 IBM Corporation Assess legacy content Analyze state of content specifically from a DITA point-of-view
  25. 25. Going the DITA way . . . 25 © 2013 IBM Corporation Assess legacy content How structured is the legacy content? Is it organized into topics already? How easy would it be to fit into the concept, reference, and task DITA topic types? Unstructured: Linear, book-type Partially structured: Relatively easy to restructure into DITA topics Structured: Entirely topic-based, but does not conform to DITA
  26. 26. Going the DITA way . . . 26 © 2013 IBM Corporation Assess legacy content Consistency makes it easier to run scripts and search and replace. Example: Bold and italic highlighting is not used consistently for command names, variables, etc.
  27. 27. Going the DITA way . . . 27 © 2013 IBM Corporation Assess legacy content Common information repeating across information units: Product names Operating system names Version numbers Standard product description Legal notices Entire documentation sets duplicated with only few differences
  28. 28. Going the DITA way . . . 28 © 2013 IBM Corporation Assess legacy content Short description Minimalism Latest style guidelines . . .
  29. 29. Going the DITA way . . . 29 © 2013 IBM Corporation Decide on the approaches  Convert in-house – Availability of development teams to answer queries – Lack of budgets to outsource or hire consultants  Outsource – Vendors who specialize in DITA migration and have the tools – Lack of time and resources to convert in-house
  30. 30. Going the DITA way . . . 30 © 2013 IBM Corporation Decide on the approaches  Clean up legacy information and then convert  Convert to DITA and then clean up
  31. 31. Going the DITA way . . . 31 © 2013 IBM Corporation Create a prototype  Select varied content types  List each step in the process  Record time spent on each step
  32. 32. Going the DITA way . . . 32 © 2013 IBM Corporation Disclaimer:  This list does not contain all the steps; it is only a small snippet of our really long task list.  This is just an example of how to create a worksheet that:  Lists the steps in a sequence  Records time taken per step for a pre-determined unit  Notes the outcome or expected result of each step against which it should be measured upon completion  The estimates are also only examples, they are not ballpark or benchmark figures that you can use or quote.
  33. 33. Going the DITA way . . . 33 © 2013 IBM Corporation Create guidelines  Linking and cross-referencing  Writing titles and short descriptions  Highlighting with semantic tags  Using graphics and screenshots  Adding metadata  Navigation structure  File naming and directory structure conventions  Common reusable content  Single-sourcing strategy
  34. 34. Going the DITA way . . . 34 © 2013 IBM Corporation Create checklists  Use the process document created during the prototype as a checklist
  35. 35. Going the DITA way . . . 35 © 2013 IBM Corporation Plan  Effort estimations  Work assignments  Timelines  Contacts  Summary or dashboard – Scope – Risks and assumptions – Resource requirements – Translation requirements
  36. 36. Going the DITA way . . . 36 © 2013 IBM Corporation Training and workshops  Refresher – DITA – Structured authoring principles – Authoring tools  Training – Conversion process – Conversion tools – Prototype demo – Guidelines and checklists
  37. 37. Going the DITA way . . . 37 © 2013 IBM Corporation Execute  Phased approach – DITA conversion accomplished fast – Avoid neither here nor there situation – DITA exploitation can be done at a slower pace – Example: End of marketing products
  38. 38. Going the DITA way . . . 38 © 2013 IBM Corporation Execute  Phase 1 – Pre-conversion tasks – Only those that are absolutely essential 1
  39. 39. Going the DITA way . . . 39 © 2013 IBM Corporation Execute  Phase 2 – Convert to DITA 1 2
  40. 40. Going the DITA way . . . 40 © 2013 IBM Corporation Execute  Phase 3 – Cleanup just enough to eliminate errors 2 1 3
  41. 41. Going the DITA way . . . 41 © 2013 IBM Corporation 1 2 3 Execute  Phase 4 – Generate output – Resolve errors – Compare with pre-conversion output 4
  42. 42. Going the DITA way . . . 42 © 2013 IBM Corporation Execute  Phase 5 – Comply with DITA model – Use the essential DITA features 4 3 2 1 5
  43. 43. Going the DITA way . . . 43 © 2013 IBM Corporation 5 Execute  Phase 6 – Incorporate other DITA features – Enhance information – Requires editorial and technical reviews 4 3 2 1 6
  44. 44. Going the DITA way . . . 44 © 2013 IBM Corporation Monitor progress  Dynamic status reports  Overall progress on dashboard  Periodic quality checks of samples  Issues resolved – FAQs to maintain consistency 6 5 4 3 2 1
  45. 45. Going the DITA way . . . 45 © 2013 IBM Corporation Tips  Migration strategy  In-house migration  Outsourced migration  Pilot project  Mixed/combination topic type  <topicgroup> element  Task topic type  DITA cleanup  Automation
  46. 46. Going the DITA way . . . 46 © 2013 IBM Corporation Migration strategy  Choose a phased approach to migration for information sets of products that are in maintenance mode.  Choose end-to-end migration for information sets of live products.  Assign work in an assembly-line approach.  Do not aim to migrate your legacy information set and release the product in the same release cycle.
  47. 47. Going the DITA way . . . 47 © 2013 IBM Corporation In-house migration  Specify the skill levels required for each role to ensure the right resources are assigned to the project.  Garner extra resources, if possible. Work with management to advertise the migration activity as a stretch assignment or with a promise of awards for contributing.  Consider getting at least a consultant (within the organization or outside) who specializes in DITA conversion projects to help with the planning and architecture.
  48. 48. Going the DITA way . . . 48 © 2013 IBM Corporation Outsourced migration  Establish what the content should look like after conversion (outcome) clearly.  Evaluate results of a pilot before handing over all content for conversion.  Create a single point of contact to co-ordinate the deliverables and schedules with the outsourcing company.
  49. 49. Going the DITA way . . . 49 © 2013 IBM Corporation Pilot project  Do not try to convert 10,000 pages/topics in the first go.  Choose the information set that covers all or most of the different facets of your legacy information because this pilot conversion will help you estimate the required effort for subsequent conversions.
  50. 50. Going the DITA way . . . 50 © 2013 IBM Corporation Mixed/combination topic type  Avoid using the mixed/combination topic type with which you can mix content from the different topic types.  Use this topic type for all your common or reusable content.
  51. 51. Going the DITA way . . . 51 © 2013 IBM Corporation <topicgroup> element  Be careful when using <topicgroup> element as a container topic because it can create empty pages in the PDF and empty topics in the HTML outputs.  If your guide is structured as “Part > Chapter > Topics”, avoid migration of Parts to <topicgroup> and use concept topics as containers.
  52. 52. Going the DITA way . . . 52 © 2013 IBM Corporation Task topic type  If you have steps nested by more than two levels, break the steps into several tasks or rewrite the task to avoid nesting steps to more than two levels.  Estimate more efforts on post-migration cleanup activity of task topics as compared to other topic types.
  53. 53. Going the DITA way . . . 53 © 2013 IBM Corporation DITA cleanup  Strive to have one topic = one file.  Delete unnecessary links. For example, if you created lists of links as a way to introduce subsections, you should delete those links or that topic altogether. If you don’t remove the links, you could get duplicate links.  Delete unnecessary topics. For example, topics that just introduce a chapter or section in your legacy information set – “This chapter ….”.
  54. 54. Going the DITA way . . . 54 © 2013 IBM Corporation Automation  Use scripts and tools as far as possible.  Befriend developers – get their help to write simple scripts.  Examples of how we used Perl scripts: – Pre-conversion: • Inserted class attribute in division tags with the value that we specified: task, reference, concept. This was later used to split information into topics. • Inserted id attribute in division tags which later were used for the topic ID, file name, and cross-references to the topic • Moved steps out of paragraph tags – Post conversion: • Renamed files using the topic IDs • Checked whether <shortdesc> tags are empty • Inserted <navtitles>
  55. 55. Going the DITA way . . . 55 © 2013 IBM Corporation Examples  Legacy info set - snippet
  56. 56. Going the DITA way . . . 56 © 2013 IBM Corporation Examples  Pre-conversion tasks
  57. 57. Going the DITA way . . . 57 © 2013 IBM Corporation Examples  Converted output where basic pre- conversion cleanup was not done properly
  58. 58. Going the DITA way . . . 58 © 2013 IBM Corporation Examples  Migrated DITA topic after post-conversion cleanup
  59. 59. Going the DITA way . . . 59 © 2013 IBM Corporation Questions? You can contact us @ abisamuel@in.ibm.com & alachary@in.ibm.com

×