An internal Adobe team arrived at these best practices while migrating data from a proprietary content management system to Adobe CQ. The migrated data was extensive:
We recommend that you create a CQ package to import a large number of nodes into the CRX repository. You can then import this package into one or more CQ instances using the CRX Package Manager. Follow these broad steps:
Notice the unresolved links towards the end of this CQ XML example. To prevent such issues, convert a cluster of linked articles together. Unresolved links indicate that the converted articles contain links to content that you haven't converted yet.
You can map semantic structures in DITA to equivalent CQ components. The internal Adobe team used these mappings:
| DITA tag | CQ component | Approach adopted during the migration under study |
| topic | page | |
| p | text | |
| ul | text | |
| ol (simple) |
text | Simple (non-nested) ordered lists were converted to the regular text component. |
| ol (complex) |
procedure | Complex ordered lists were converted to the procedure component. procedure is a container component that allows multiple nested components, such as text and images. |
| image | image | The CQ component was specialized to store information, such as callouts, scales, and statuses. |
| dl | variable-entry | Definition lists were converted into a structure that separates the term from the definition. The term is entered in a regular text field, while the definition is entered in a rich text field. |
| draft-comment | comment | |
| code | code-block | |
| title | heading | |
| related-link | related-link | |
| table | table | |
| note | note | |
| tip | tip |
When adding assets to the Digital Asset Management (DAM) system, remember to create the folder nodes of the type jcr:primaryType=sling:orderedFolder. You cannot add or delete assets through the DAM editor interface using regular folder nodes (nt:folder).
While migrating content, evaluate whether you want to share assets across articles. For example, screenshots in a Photoshop article are usually not relevant to an Adobe Illustrator article. Rather than placing these assets in the DAM system, you can migrate them as file nodes under their respective document nodes.
Placing images under the document nodes preserves the parent-child relationship between the document and images. Additionally, this approach doesn't require a parallel directory structure in the DAM system, realizing the following benefits:
Because icons are frequently shared between documentation suites, consider storing them in the DAM system rather than migrating them as file nodes.
Twitter™ and Facebook posts are not covered under the terms of Creative Commons.
