Documentation differences

Documentation Differences and Updated Guidelines

---

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.

1. 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.

2. 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.

1. 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.

2. Content Specifics

• Startup Configuration: Detailed guidance on configuring Optimizely services in Program.cs or the minimal hosting model.

// Conceptual example of CMS service configuration in .NET 6+

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddCms()
    .AddCommerce();

var app = builder.Build();

app.UseRouting();
app.MapControllers();

app.Run();

• 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.
• Deployment Guidance: Modern deployment approaches including cloud environments and containerization.

---

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 (e.g., Content Cloud 12 or Commerce Cloud 14) is selected.
• Avoid Legacy Confusion: Do not rely on CMS 11 or Commerce 13 documentation for new implementations.

2. Leverage Search and Navigation

• Use Targeted Keywords: Include version-specific terms such as "CMS 12 configuration" or "Commerce 14 API."
• Explore Related Topics: Use the table of contents to understand feature relationships and dependencies.

3. Understand the DXP Ecosystem

• Integrated Components: CMS, Commerce, Search & Navigation, and Personalization documentation are interconnected.
• Holistic View: Understanding overall DXP architecture improves implementation clarity.

---

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.

---