Re: [dita] Starting thoughts on a migration document

["Robert D Anderson" <robander@us.ibm.com>]

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ë