Main Content
Picture of Instruction

Better Instructions for Your Drupal Content Types

Besides Title, the most common field label found on a content type form is Body. Of course, this is where you place the body of your content. It’s your blog post, your how-to instructions, or maybe an event description. You know exactly what needs to be provided in this field because you are the trained author. What happens when the scenario includes many authors with varied skills?

Without clearly visible instructions for the form and the form fields, content authors can make mistakes. There are four default features in Drupal 8 that provide instructions for content authors.

Help

Body field configuration interface

When configuring a field, all fields except Title, you can include help text. The help text appears under the field, just like you see here on the configuration form where the help text for the help text field says, “Instruction to present to the user below this field on the editing form.”

Pros

The label of a field might not communicate the full intent or purpose of the field, so adding instructions in the help field can go a long way to ensuring an author uses the field correctly. 

For example, the Tags field on the Article content type provides default help text: Enter a comma-separated list. For example: Amsterdam, Mexico City, "Cleveland, Ohio" This provides instructions for entering tags correctly. 

However, if you need to add additional instruction regarding the context of the tags, you can include a statement like, “Do not use terms already offered in the Topics field.” 

Cons

The common placement of instructions below a field isn’t always noticeable. For example, the screenshot below shows the body field with help text below. Is it eye catching? Obvious?

Body field on the Add node page.

The size of a field can make providing easy to see instructions a challenge. And, if you need to make an accessible content type, the help text feature needs a little work to make it WCAG compliant. 

Placeholder

Configuration options for Body field on the Manage form display

Using placeholder text inside the field is another option. Although this feature is not available for all field types, it does enable you to include 128 characters of instructions. Located on the Manage Form Display tab for the content type, it’s just one configuration option available.

Pros

As mentioned in the Help section above, the Title field doesn’t have a help text option. However, the placeholder feature is available to provide tips on title strategies. Or, if the instruction is short and simple, such as a date format of MM/DD/YYYY can help users quickly understand the sequence of the date parts.

Cons

It’s only 128 characters and if the field size is less that that, not all of the instructions will be visible. On the topic of visibility, the Placeholder feature is not read by a screen reader. And, unless you do some browser specific CSS overrides, the contrast of Placeholder text might not meet WCAG color contrast criterion.

Lastly, when a user clicks in the field to enter data, the placeholder text disappears.  

Default Values

Body field default content configuration interface

The default value feature for fields is a great way to speed up data entry when the same entry is expected frequently. However, it can also be used to communicate instructions to the content author. You can go as far as providing a content template where the appropriate formatting has already been applied. 

Pros

Uniformity. Clarity. An experienced author will have their own way of conveying their thoughts, but that way isn’t always what’s best for an organization. Or, a newbie writer might need a little help to get started.

Notice the instructions for the often forgotten Summary feature. If you require a summary, include instructions like those shown in the example above and the Summary field will be open and ready when the content author uses the content type.

Also, unlike the Placeholder option, clicking in the field does not make the instructions disappear. 

Cons

The content author needs to remember to delete the instruction text. A small price to pay.

Content Type Explanation/Guidelines

Submission field settings for the content type

According to the Form Instructions tutorial provided by W3C, “Where relevant, provide overall instructions that apply to the entire form.” Each content type has the option to include a form explanation or submission guideline, as the field label suggests. 

Pros

Content add form with submission guidelines sample text.

The form explanation appears just above the Title field and outside the <form> element, which is needed for accessibility. You can also include HTML elements to format your instructions. 

Cons

If you need to format your form instructions, you will need to enter your own HTML as there is no HTML editor bar.

Conclusion

Not all forms are self-explanatory. Not all field purposes can be easily deduced. Drupal provides several options for providing guidance to your content authors, each with their own pros and cons. 

As you plan the way your finished content will be presented to site visitors, remember to plan your content type forms. Just because a content author receives training when the site is delivered, that doesn’t mean they will remember everything they learned. Form instructions help.