Best practices

Make it easy to use

When designing the authoring interface, focus on simplicity and ease of use. Content authors should be able to use it without technical training.

Reusing the same components where possible not only ensures consistency but also helps content authors to become familiar with the user interface. Grouping related fields together is another way to customize the editing experience, making the process more intuitive and user-friendly.

In addition, rather than making content authors start from a blank slate every time or need to duplicate an existing full page repeatedly, give them templates.

Nested vs. flat editing experience

Content should be nested thoughtfully. For example, you can group similar content together to allow authors to move one container, rather than move its pieces individually, up or down the page. Nested content may also be necessary for creating columns.

Poorly structured nested content models can easily waste hours of a content author’s time. Each layer of a nested content model can slow a content author by more than 5 seconds.

Watch below as an author navigates nested content to add one button to the home page. With a flat editing experience, the author could have added a button as soon as they opened the home page.

An author navigates nested content in Contentful to add one button to the home page.

Early and continuous author feedback

To create a successful authoring experience, it's crucial to consider the unique needs of your content authors and the specific requirements of your business.

When migrating a website to a headless platform, prioritize building what's most important to the business first:

• Which pages or components are essential to the bottom line?

• Which pages are the most frequently updated?

• What are the content workflows?

Focus on delivering what's required to build the most crucial and urgent pages. The first version shouldn't be an assortment of components that cannot be assembled into pages.

Build a working v1, and bring authors in to try it. Iterate, to ensure it meets their needs.

By taking an iterative approach and incorporating user feedback as you build, you can anticipate author needs and address issues that only become apparent during user testing. This results in a more usable and effective authoring experience.

Documentation

Provide clear and concise documentation for the authoring experience, including guidelines for content creation and best practices for using the CMS. Add walkthrough videos, tutorials, and written guides wherever documentation lives at your organization.

We also recommend using Storybook as part of your development workflow to help developers visualize and test what they're building.

Storybook also doubles as a comprehensive component catalogue for content authors. It's hosted separately, so designers and other teams can see all available components without requiring access to your CMS.

Storybook doubles as a reference catalogue for content authors.

Provide clear instructions

Use helper texts to let users know what to input. Specify requirements, such as ideal image aspect ratios, file format, and text length. This helps standardize how components are used and how pages look.

Example of a descriptive helper text. Publish Date: This date will appear as the publish date on the article.

Consider who will be using the headless CMS, and tailor the instructions to their specific needs and use cases. For example, let's say a media module on an event landing page is intended to share information about an upcoming event; "event date" is clearer than "header."

You can also use visual cues such as icons, colour coding, and field labels to guide users and make the experience more intuitive.

An example of fields in Sanity with poor visual indicators.

The same fields in sanity with good visual indicators showing blog title, publish date and featured image.

Use language that is easy for non-technical users to understand. Be concise, and avoid overwhelming authors with verbose or unnecessary information.

Validation messages

Provide content authors with helpful feedback as they work in the CMS, such as alerts for missing or incorrect fields. This helps them create content more efficiently and with fewer errors.

Mark required fields so they don't assume it's optional, skip it, and become confused by why their page isn't building.

A required field is highlighted in red and denoted as being required using an icon.

Validation messages should be specific and indicate exactly what is wrong with the content. For example, instead of something generic like "Invalid input", provide a specific message like "File format: png or jpg."

A validation message warns user that the title is too long and should be 256 characters or shorter.

The message should also indicate how to correct the error. This could be in the form of a helpful hint, a link to a relevant document, or a suggestion for what type of content can be added.

Validation messages should be displayed prominently and near the field that needs to be corrected. This will make it easy for content authors to understand where the issue is and how to address it.

Test validation messages with real content authors to ensure they are effective and provide helpful guidance. Iterate the messages, as needed, based on user feedback to continuously improve the authoring experience.