OASIS Darwin Information Typing Architecture (DITA) TC

I have thoughts on a very (very) rough outline of a migration document for DITA 2.0. Overview of changes (would this be more or less detailed than the spec?) Migrating DITA Source Migrating DITA Tools Each Migrating section would have a similar structure: Overview of suggested method Suggested tools Prepare for migration (analysis, get nifty scripts from GitHub, etc.) Easy things - stuff that can be done with search and replace or some quick tool Moderately complicated things - minor refactoring, such as taking all @alt and moving to <alt> Hard things - stuff that requires rewriting/reworking Optional things - e.g. here are new elements/attributes you might want to use Clean up The order of operations subject to change based on whatever it is we actually need to do. E.g. if you need to fix X before you can do Y, even if it's hard, it needs to come earlier in the order. Each set of tasks would have all the base tasks first, then the technical content, etc. The theory is that you can step through the document once and have migrated content at the end.  I have never really extended DITA, so I'm ignorant. Does there need to be a different section for migrating specializations/extensions? Or is that just part of Migrating DITA Source? I'm sure there will be much discussion about what is "easy" vs "hard", since that can be super subjective, but at least it's a start. Zoë

I can see a couple of ways to approach it and I'm honestly not sure which is best. Maybe both are appropriate, but for different audiences. Approaching things in sequence as individual items is most useful as a "this is what changed" informative doc. "This changed; you need to update X to Y; here are ways to do it." But if I'm either 1) writing a tool to automate this, or 2) updating my own content in the absence of a tool, I would hope for some combination of: - A simple list of all the things to update with search/replace in your content - Another list of things that require manual cleanup in source (look for this, and fix it based on your conditions) - Any updates to source files that won't fit into those categories? Not sure offhand what that would be - Simple list of what needs to be updated in grammar files with search/replace (like updates to class attributes) - Another list of manual fixes in grammar files I don't know what others would want though. That sort of organization is really better for someone who either already knows what is changing, or doesn't care why things are changing - just wants the list of things to fix. But thinking on that more -- that almost sounds like an appendix to the document you've described. Full migration doc does what you originally suggested, then a "Here are the changes" summary that conref's in the critical bits? Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification Marketing Services Center E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Zoe Lawson ---10/15/2019 09:22:59 AM---I have thoughts on a very (very) rough outline of a migration document for DITA 2.0. * Overview From: Zoe Lawson <zoelawson17@hotmail.com> To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org> Date: 10/15/2019 09:22 AM Subject: [EXTERNAL] [dita] Starting thoughts on a migration document Sent by: <dita@lists.oasis-open.org> I have thoughts on a very (very) rough outline of a migration document for DITA 2.0. Overview of changes (would this be more or less detailed than the spec?) Migrating DITA Source Migrating DITA Tools Each Migrating section would have a similar structure: Overview of suggested method Suggested tools Prepare for migration (analysis, get nifty scripts from GitHub, etc.) Easy things - stuff that can be done with search and replace or some quick tool Moderately complicated things - minor refactoring, such as taking all @alt and moving to <alt> Hard things - stuff that requires rewriting/reworking Optional things - e.g. here are new elements/attributes you might want to use Clean up The order of operations subject to change based on whatever it is we actually need to do. E.g. if you need to fix X before you can do Y, even if it's hard, it needs to come earlier in the order. Each set of tasks would have all the base tasks first, then the technical content, etc. The theory is that you can step through the document once and have migrated content at the end. I have never really extended DITA, so I'm ignorant. Does there need to be a different section for migrating specializations/extensions? Or is that just part of Migrating DITA Source? I'm sure there will be much discussion about what is "easy" vs "hard", since that can be super subjective, but at least it's a start. Zoë

Let's think about audiences for this document. Below is a very rough start, done off the-top-of-my-head ... DITA practitioners who will be updating an implementation's document-type shells . These folks will need to: Look at bookmap Be aware if we remove domains from shells that integrated them for earlier versions of DITA DITA practitioners who will be updating specializations and constraint modules for an implementation. These folks will care about: Deprecated elements and attributes that were part of their specialization or constraint modules, but are removed from DITA 2.0 Elements for which we changed the specialization base DITA practitioners who will be updating implementations' stylesheets . These folks will care about: Elements for which we changed the specialization base New elements and domains DITA architects who are in charge of an implementations' DITA source . These folks will care about: Deprecated elements and attributes that were part of their specialization or constraint modules, but are removed from DITA 2.0 DITA tools that produce a rendered view of the DITA source (editors, CCMS) New or modified elements will need to be styled using CSS, XSLT, or a combination of CSS and XSLT DITA tools that process DITA source to produce output formats Need to add features to address use cases previously handled by @copy-to A question -- Do we restrict this document to migration, or do also cover new to DITA 2.0 elements, attributes, and functionality that tools/processors/etc will need to make changes to support? My list above combines the two; stuff specifically relating to new to DITA 2.0 elements, attributes, and functionality highlighted in blue . Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) On 10/15/2019 10:22 AM, Zoe Lawson wrote: I have thoughts on a very (very) rough outline of a migration document for DITA 2.0. Overview of changes (would this be more or less detailed than the spec?) Migrating DITA Source Migrating DITA Tools Each Migrating section would have a similar structure: Overview of suggested method Suggested tools Prepare for migration (analysis, get nifty scripts from GitHub, etc.) Easy things - stuff that can be done with search and replace or some quick tool Moderately complicated things - minor refactoring, such as taking all @alt and moving to <alt> Hard things - stuff that requires rewriting/reworking Optional things - e.g. here are new elements/attributes you might want to use Clean up The order of operations subject to change based on whatever it is we actually need to do. E.g. if you need to fix X before you can do Y, even if it's hard, it needs to come earlier in the order. Each set of tasks would have all the base tasks first, then the technical content, etc. The theory is that you can step through the document once and have migrated content at the end.  I have never really extended DITA, so I'm ignorant. Does there need to be a different section for migrating specializations/extensions? Or is that just part of Migrating DITA Source? I'm sure there will be much discussion about what is easy vs hard , since that can be super subjective, but at least it's a start. Zoë

Some specific thoughts about migration for practitioners who have created specialization or constraint modules ... For the most part, I think this can be handled almost with a simple flow (although I'm sure that I am missing something obvious): Have you specialized any of the following elements? [Followed by a list of elements with changes to content models, attributes, or specialization base]  No -- You're good. Yes -- You've got some work to do. Do your constraint models reference any elements or attributes that have been removed? No -- You're good. Yes -- You've got some work to do. Have you constrained any elements for which we have modified the content model model or attributes? No -- You're good. Yes -- You've got some work to do. Robert, how would changes that we've made to entities or the filter attributes affect this? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) On 10/15/2019 10:22 AM, Zoe Lawson wrote: I have thoughts on a very (very) rough outline of a migration document for DITA 2.0. Overview of changes (would this be more or less detailed than the spec?) Migrating DITA Source Migrating DITA Tools Each Migrating section would have a similar structure: Overview of suggested method Suggested tools Prepare for migration (analysis, get nifty scripts from GitHub, etc.) Easy things - stuff that can be done with search and replace or some quick tool Moderately complicated things - minor refactoring, such as taking all @alt and moving to <alt> Hard things - stuff that requires rewriting/reworking Optional things - e.g. here are new elements/attributes you might want to use Clean up The order of operations subject to change based on whatever it is we actually need to do. E.g. if you need to fix X before you can do Y, even if it's hard, it needs to come earlier in the order. Each set of tasks would have all the base tasks first, then the technical content, etc. The theory is that you can step through the document once and have migrated content at the end.  I have never really extended DITA, so I'm ignorant. Does there need to be a different section for migrating specializations/extensions? Or is that just part of Migrating DITA Source? I'm sure there will be much discussion about what is easy vs hard , since that can be super subjective, but at least it's a start. Zoë

This is a great list of audiences I didn’t even think of, thank you. In my brain, migration includes new things. A major reason you upgrade is to get new features, so you should know how to take advantage of them. However, I’d describe these as “optional”. Zoë Get Outlook for iOS From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com> Sent: Wednesday, October 16, 2019 11:32:10 AM To: dita@lists.oasis-open.org <dita@lists.oasis-open.org> Subject: Re: [dita] Starting thoughts on a migration document   Some specific thoughts about migration for practitioners who have created specialization or constraint modules ... For the most part, I think this can be handled almost with a simple flow (although I'm sure that I am missing something obvious): Have you specialized any of the following elements? [Followed by a list of elements with changes to content models, attributes, or specialization base]  No -- You're good. Yes -- You've got some work to do. Do your constraint models reference any elements or attributes that have been removed? No -- You're good. Yes -- You've got some work to do. Have you constrained any elements for which we have modified the content model model or attributes? No -- You're good. Yes -- You've got some work to do. Robert, how would changes that we've made to entities or the filter attributes affect this? Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) On 10/15/2019 10:22 AM, Zoe Lawson wrote: I have thoughts on a very (very) rough outline of a migration document for DITA 2.0. Overview of changes (would this be more or less detailed than the spec?) Migrating DITA Source Migrating DITA Tools Each Migrating section would have a similar structure: Overview of suggested method Suggested tools Prepare for migration (analysis, get nifty scripts from GitHub, etc.) Easy things - stuff that can be done with search and replace or some quick tool Moderately complicated things - minor refactoring, such as taking all @alt and moving to <alt> Hard things - stuff that requires rewriting/reworking Optional things - e.g. here are new elements/attributes you might want to use Clean up The order of operations subject to change based on whatever it is we actually need to do. E.g. if you need to fix X before you can do Y, even if it's hard, it needs to come earlier in the order. Each set of tasks would have all the base tasks first, then the technical content, etc. The theory is that you can step through the document once and have migrated content at the end.  I have never really extended DITA, so I'm ignorant. Does there need to be a different section for migrating specializations/extensions? Or is that just part of Migrating DITA Source? I'm sure there will be much discussion about what is "easy" vs "hard", since that can be super subjective, but at least it's a start. Zoë --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php