What two Contentful builds taught us about content models and publishing boundaries

两次 Contentful 项目开发教会我们的内容建模与发布边界经验

For Addiction Education Society (AES), we modeled resources, stories, and core pages in Contentful so staff could update the public site without developer support. The team now publishes changes in minutes rather than days. 对于成瘾教育协会（AES）而言，我们在 Contentful 中对资源、故事和核心页面进行了建模，以便员工无需开发人员支持即可更新公共网站。现在，该团队发布变更的时间已从几天缩短至几分钟。

For CrewAI, we mapped reusable page components to Contentful models, then built a separate handoff that turns published Ghost articles into Contentful drafts. Both projects used the same content management system (CMS). The useful engineering decision was where to place editorial control, rendering rules, and the final publication gate. 对于 CrewAI，我们将可复用的页面组件映射到 Contentful 模型，并构建了一个独立的交接流程，将已发布的 Ghost 文章转换为 Contentful 草稿。这两个项目使用了同一个内容管理系统（CMS）。其中关键的工程决策在于：如何分配编辑控制权、渲染规则以及最终的发布门槛。

A headless CMS stores structured content separately from the code that renders it. That separation helps only when the content model reflects what editors need to create and what engineers need to keep consistent. These projects exposed 3 questions worth answering before migrating a page: What is reusable content? Which system owns each step of publication? Which existing systems should stay in place? 无头 CMS 将结构化内容与渲染代码分离开来。只有当内容模型既能反映编辑的创作需求，又能满足工程师的一致性要求时，这种分离才有意义。这些项目提出了在迁移页面前值得思考的三个问题：什么是可复用的内容？发布流程的每个环节由哪个系统负责？哪些现有系统应该保留？

Model the things editors actually manage

为编辑实际管理的内容建模

At AES, the main requirement was editorial independence. Staff needed to maintain information as the nonprofit’s education and outreach work grew. We created Contentful models for resources, stories, and core pages. Those categories gave the team structured material to build and update pages independently, including for time-sensitive initiatives. The AES case study reports that updates which took days can now be published in minutes. 在 AES，主要需求是编辑的独立性。随着该非营利组织教育和外联工作的增长，员工需要自行维护信息。我们为资源、故事和核心页面创建了 Contentful 模型。这些分类为团队提供了结构化素材，使他们能够独立构建和更新页面，包括针对有时效性的项目。AES 案例研究显示，过去需要几天完成的更新，现在几分钟即可发布。

CrewAI needed a different level of composition. Its previous CMS could no longer support the website it needed. We designed reusable components in Figma, including hero layouts, pricing sections, feature grids, statistics modules, and tabbed content. Each component mapped to a structured Contentful model. Marketing could assemble pages from those blocks, while developers rendered the layouts through GraphQL with strong type safety. CrewAI 则需要不同层级的组合能力。其之前的 CMS 已无法支持所需的网站功能。我们在 Figma 中设计了可复用组件，包括首屏布局、定价板块、功能网格、统计模块和标签页内容。每个组件都映射到一个结构化的 Contentful 模型。市场团队可以利用这些模块组装页面，而开发人员则通过具有强类型安全的 GraphQL 来渲染布局。

In the CrewAI case study, the shift from individual templates to reusable sections is the mechanism behind that division of work. The model therefore served as a contract. An editor could choose and populate a supported section; engineering owned how that section rendered and how it fit with analytics, search optimization, and integrations. Contentful’s reference based type system makes these relationships possible, but the types still have to be designed. A collection of loosely related entries would give editors fields to fill without giving the site a dependable composition system. That is the modeling cost we account for up front. 在 CrewAI 的案例中，从单一模板转向可复用板块是实现工作分工的机制。因此，模型充当了“契约”的角色。编辑可以选择并填充受支持的板块；而工程团队则负责该板块的渲染方式，以及它如何与分析工具、搜索优化和集成服务相配合。Contentful 基于引用的类型系统使这些关系成为可能，但类型本身仍需精心设计。如果只是一堆松散关联的条目，虽然能提供给编辑填写的字段，却无法为网站提供可靠的组合系统。这就是我们预先考虑的建模成本。

Draw the migration boundary around the work

围绕工作内容划定迁移边界

AES also shows why a CMS migration does not have to mean replacing every application under a domain. Its WordPress learning system supported active educational programs. Rebuilding that system along with the marketing site would have risked downtime or lost functionality. We launched a new marketing platform using Astro and Contentful alongside the existing learning system. Public pages, articles, and donation flows were modernized while the programs continued. Visitors still had an experience under one domain, and AES retained a path to migrate more functionality later. AES 的案例还表明，CMS 迁移并不意味着必须替换域名下的所有应用程序。其 WordPress 学习系统支撑着活跃的教育项目。如果将该系统与营销网站一并重建，将面临停机或功能丢失的风险。我们使用 Astro 和 Contentful 构建了新的营销平台，并与现有的学习系统并行运行。在项目持续进行的同时，公共页面、文章和捐赠流程得到了现代化升级。访问者在同一个域名下依然拥有连贯的体验，且 AES 保留了后续迁移更多功能的路径。

That boundary mattered operationally. Staff gained control of public content without waiting for the learning platform to be rebuilt. The Contentful work solved a publishing problem; the surrounding architecture kept an existing program available. The project also used Contentful’s pro bono program, which made the platform accessible to this qualifying nonprofit. Pricing was part of the platform decision, even though the implementation followed the same content modeling discipline as a larger site. 这种边界在运营上至关重要。员工无需等待学习平台重建，即可获得对公共内容的控制权。Contentful 的应用解决了发布问题，而周边的架构则确保了现有项目的可用性。该项目还利用了 Contentful 的公益计划，使该符合条件的非营利组织能够使用该平台。定价是平台决策的一部分，尽管其实现过程遵循了与大型网站相同的内容建模准则。

CrewAI crossed a different boundary. We moved its site away from page specific templates toward structured sections in Contentful, but kept Ghost for article writing. Treating every existing tool as something to replace would have disrupted a workflow the editorial team already valued. The two projects suggest a practical migration exercise: list the tasks people perform in each system, then move only the tasks the new architecture is meant to improve. CrewAI 则跨越了不同的边界。我们将网站从特定页面模板迁移到了 Contentful 的结构化板块，但保留了 Ghost 用于文章撰写。如果将所有现有工具都视为需要替换的对象，将会破坏编辑团队已经习惯的工作流。这两个项目提供了一个实用的迁移练习：列出人们在每个系统中执行的任务，然后仅迁移那些新架构旨在改进的任务。

Make the publication gate explicit

明确发布门槛

CrewAI’s writers publish articles in Ghost. An automated workflow converts each published Ghost article into a draft in Contentful. It stops there deliberately. Marketing then reviews the content, adds metadata, adjusts page composition, schedules it, and publishes it to the public site. Ghost owns the writing experience; Contentful owns the website release decision. CrewAI 的作者在 Ghost 中发布文章。自动化工作流会将每篇已发布的 Ghost 文章转换为 Contentful 中的草稿。流程特意在此处停止。随后，市场团队会对内容进行审核、添加元数据、调整页面组合、设置排期，并将其发布到公共网站。Ghost 负责写作体验，而 Contentful 负责网站的发布决策。

The draft state is the critical part of that integration. If the handoff went straight to public publication, the team would lose the documented review and enrichment step. If writers had to repeat their work manually in Contentful, the handoff would become another editorial bottleneck. The Contentful project page describes this pipeline as the integration point; the case study shows the specific roles on each side of it. This is a useful question for any CMS integration: does an upstream “published” event mean ready for the public website, or ready for the next team to review? In CrewAI’s workflow, those are separate states. Naming them in the architecture gives both teams a clear handoff and lets each keep the tool suited to its work. 草稿状态是该集成的关键部分。如果交接直接进入公开发布，团队将失去记录在案的审核和丰富内容环节。如果作者必须在 Contentful 中手动重复工作，交接就会成为另一个编辑瓶颈。Contentful 项目页面将此流水线描述为集成点；案例研究展示了双方的具体角色。对于任何 CMS 集成，这都是一个有用的问题：上游的“已发布”事件意味着已准备好发布到公共网站，还是准备好供下一个团队审核？在 CrewAI 的工作流中，这是两个独立的状态。在架构中明确命名这些状态，可以为两个团队提供清晰的交接，并让双方都能保留最适合其工作的工具。

Choose the platform with its constraints visible

在看清约束的前提下选择平台

Contentful gave AES structured content and staff publishing control; it gave CrewAI reusable page composition and a controlled handoff from Ghost. Neither outcome came from installing a CMS alone. We had to define content types, decide which existing systems would remain, and specify the point where a draft becomes public. The platform also has costs. Its type system rewards careful modeling, and the Contentful project page notes both the budget impact and the absence of a built-in visual canvas for page building. For a small team with simple pages, that may be more structure than the work requires. For a site where several teams need to assemble pages and govern releases, the structure is essential. Contentful 为 AES 提供了结构化内容和员工发布控制权；为 CrewAI 提供了可复用的页面组合以及从 Ghost 的受控交接。这些成果并非仅靠安装一个 CMS 就能实现。我们必须定义内容类型，决定保留哪些现有系统，并明确草稿何时变为公开。该平台也有其成本。其类型系统要求进行精细的建模，Contentful 项目页面也指出了预算影响以及缺乏内置页面构建可视化画布的问题。对于页面简单的精简团队来说，这可能超出了工作所需的结构复杂度。但对于需要多个团队协作组装页面并管理发布的网站而言，这种结构是必不可少的。