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ë