Collaborating with Developers

Successful content management requires clear communication between editors and developers. This guide helps both sides collaborate effectively.

The Handoff Process

When creating new pages or sections, follow this workflow:

sequenceDiagram
    actor Editor
    actor Developer
    
    Editor->>Developer: Request new section type
    Developer->>Developer: Creates component + block
    Developer->>Editor: Provides section slug and block fields
    Editor->>Editor: Creates section in admin
    Editor->>Editor: Attaches to page
    Editor->>Developer: Reports issues or requests changes

What Editors Need from Developers

When a developer creates a new section component, they should provide:

1. Section Slug

The exact slug to use when creating the section:

Component: Hero
Slug: hero

2. Block Fields

A list of all fields the section accepts:

Field	Type	Required	Description
label	Text	Yes	Small text above headline
headline	Text	Yes	Main heading
primary_cta_text	Text	No	Button text
primary_cta_url	URL	No	Button link
features	Repeater	No	List of features

3. Preview Information

• What the section looks like
• Where it should be used
• Any special behaviors

What Developers Need from Editors

When requesting a new section, editors should provide:

1. Content Requirements

• What text fields are needed
• What image sizes are required
• Any repeating content (lists, grids)

2. Design Context

• Screenshot or mockup
• Example content
• Responsive behavior expectations

3. Usage Context

• Which pages will use it
• Will it be reused across pages
• Expected content update frequency

Example Request

Editor to Developer:

I need a “Pricing Cards” section for the pricing page. It should show 3 pricing tiers side by side. Each card needs:

• Plan name (e.g., “Basic”, “Pro”, “Enterprise”)
• Price (e.g., “$29/mo”)
• Feature list (repeating text items)
• CTA button text and URL

Here’s a mockup: [screenshot] It will only be used on the pricing page.

Developer Response:

Created the PricingCards component. Use slug pricing-cards. Fields:

• plan_name (text, required)
• price (text, required)
• features (repeater of text items)
• cta_text (text)
• cta_url (text)

Updating Existing Sections

For small text changes, use Visual Editing.

For structural changes (new fields, different layouts), work with a developer:

1. Describe what needs to change
2. The developer updates the component and block
3. You update the section content in the admin

Troubleshooting

Problem	Likely Cause	Solution
Section not appearing	Wrong slug	Verify slug matches component name
Content not showing	Wrong block type	Check block type matches Block::make() name
Changes not reflecting	Cache	Clear browser cache or ask developer to clear view cache
Field missing	Component not updated	Ask developer to add the field

Best Practices

• Document all sections in a shared spreadsheet
• Keep a changelog of section updates
• Test new sections on a staging site first
• Communicate early about upcoming content needs
• Respect each other’s workflows and timelines

Next Steps

• Managing Sections
• Visual Editing