Documentation differences
Outline
- Major shift: Documentation now centers entirely around ASP.NET Core and .NET 6+ development patterns.
- Version awareness: CMS 12 and Commerce 14 documentation is strictly versioned - legacy CMS 11 guidance no longer applies.
-
Modern focus: Emphasis on dependency injection, middleware, configuration via
Program.cs, and cloud-native deployment. - Developer responsibility: Always verify product version context before following implementation guidance.
Introduction
This module addresses the evolution of Optimizely's documentation landscape following the release of CMS 12 and Commerce 14. With the fundamental shift to ASP.NET Core, the underlying architecture and development patterns have changed significantly, necessitating corresponding updates and new guidelines in the official documentation.
This section highlights key documentation differences, explains how to locate relevant and up-to-date resources, and outlines best practices for effectively leveraging documentation during migration and ongoing development.
The Evolution of Optimizely Documentation
The transition to ASP.NET Core for CMS 12 and Commerce 14 resulted in a comprehensive overhaul of developer documentation. Previous documentation focused on ASP.NET Framework is now considered legacy for new implementations.
What changed and why
Select a topic to expand and read the details.
Version-specific documentation ▼
- Clear versioning: Documentation is meticulously versioned. Always reference CMS 12 (Content Cloud) and Commerce 14 (Commerce Cloud) documentation when working with these platforms.
- Separate guides: Distinct documentation exists for Content Cloud (CMS), Commerce Cloud, and broader DXP components. Mixing guidance between these can produce subtle errors.
Shift in focus and content ▼
- ASP.NET Core centric: Documentation now emphasizes dependency injection, middleware pipelines, endpoint routing, and the new configuration model.
- Modern development practices: Stronger focus on cloud-native architecture, API-first design, and scalable deployment strategies.
- Deprecation guidance: Clear identification of deprecated APIs and migration paths to their modern equivalents.
Key Differences in Documentation Structure and Content
Understanding how documentation is structured significantly improves development efficiency.
Structure and navigation
- Modular organization: Content is organized into task-based, feature-specific sections for easier navigation.
- Improved search: Enhanced search functionality allows quick discovery of version-relevant documentation.
- Consistent code samples: Examples are provided using ASP.NET Core-compatible C# patterns throughout.
Startup configuration
Detailed guidance on configuring Optimizely services in Program.cs using the minimal hosting model is now a primary documentation focus. The following example illustrates the new pattern:
Additional content areas
- Dependency injection: Comprehensive coverage of extending and customizing services using the built-in DI container.
- API changes: Updated documentation on content loading, saving, and event handling changes between versions.
- Deployment guidance: Modern deployment approaches including cloud environments and containerization.
Note: The old ASP.NET Framework startup pattern using Startup.cs with separate ConfigureServices and Configure methods does not apply to CMS 12. Documentation referencing this pattern is legacy.
Updated Guidelines for Effective Documentation Usage
To maximize the effectiveness of documentation during migration and development, teams should follow structured practices.
1. Always verify version context
- Confirm version selector: Ensure the correct product version (for example, Content Cloud 12 or Commerce Cloud 14) is selected before reading any implementation guidance.
- Avoid legacy confusion: Do not rely on CMS 11 or Commerce 13 documentation for new implementations - patterns, APIs, and configuration models differ significantly.
Important: Search engine results and community forum answers frequently surface legacy documentation. Always verify the version context of any guidance you find externally before applying it to a CMS 12 or Commerce 14 codebase.
2. Leverage search and navigation
- Use targeted keywords: Include version-specific terms such as "CMS 12 configuration" or "Commerce 14 API" to filter results to relevant documentation.
- Explore related topics: Use the table of contents to understand feature relationships and dependencies before implementing a solution.
3. Understand the DXP ecosystem
- Integrated components: CMS, Commerce, Search and Navigation, and Personalization documentation are interconnected. A change in one area often has documented implications for the others.
- Holistic view: Understanding overall DXP architecture improves implementation clarity and reduces rework when integrating multiple platform components.
Pro tip: When onboarding new developers to a CMS 12 project, a short documentation orientation - covering how to find the version selector, where to find migration notes, and how the DXP component docs relate to each other - pays dividends quickly. It prevents the most common version-confusion mistakes before they happen.
Conclusion
The documentation for CMS 12 and Commerce 14 reflects the platforms' transition to modern ASP.NET Core architecture. By maintaining strict version awareness, understanding structural differences, and adopting disciplined documentation usage practices, development teams can reduce migration friction and ensure alignment with current best practices.
The investment in understanding how the documentation is organized - not just what it says - consistently pays off across the full lifecycle of a CMS 12 implementation.