Description

The CCS organization is implementing Adobe Experience Manager (AEM) Guides as the new authoring and publication tooling. The new publication tools will provide a cloud-based authoring and publishing platform. The platform is a DITA-based content management system. A new metadata strategy along with the opportunity for the OpenShift Virtualization product documentation to organized by topic type will lead to better search capabilities for our customers.

The Virtualization book will be able to be published independently from the larger OpenShift content, while still retaining links and cross-references to the core OpenShift Container Platform documentation.

Restructuring the content will lead to a better documentation experience by our customers.

Goals

• Prepare existing content to be migrated to DITA
• Migrate the CNV product documentation, including all supported versions, to the new AEM platform.
• Restructure content to improve findability, navigation, and search results.
• Determine whether OpenShift Virtualization content should continue to be published upstream to OKD.io

Migration prep

To prepare the CNV product documentation to migrate to AEM and DITA, we have identified key areas that require formatting updates to facilitate the content migration process.

• missing modular documentation content type
• Incorrect AsciiDoc markup
• Incompatible AsciiDoc markup
• Ignored markup that is not supported by DITA

Risks

• Content will be restructured and URLs will change. There will be no 1:1 mapping of previous documentation to the new version.
• Migration preparation and activities will compete for writing resources against feature development. 
• Learning curve of new tool will decrease writing velocity. (short-term risk)
• PR automation strategy will need to be reviewed.