Sitecore Tip #5: Provide Sitecore Field Help Information
Vasiliy Fomichev
In Best Practices, Development Posted February 05, 2014
Nobody appreciates Sitecore field help information more than Content Editors and people that have to train them. Even little tips that explain the use of what may seem to be a straight-forward field can save a lot of frustration for Sitecore editors, and keep the trainers’ mailboxes reasonably clean.
Of course we can use field validation to check user input, however, that violates some of the basic usability principles. As Sitecore developers, it is our responsibility to empower users not only with ability to edit content, but also create user-friendly and intuitive tools that can be easily understood and used by almost anyone. One of the fatal mistakes on Websites That Suck states that a website failed if “It takes longer than three seconds for the man from Mars to understand what our site is about.” I have carried this principle into my projects in Sitecore, in fact, it turns out that one of the key factors that people from Mars (i.e. a Content Editors) look for to understand what is happening on a web page is help information.
What is Sitecore Field Help Information?
Each Sitecore field may include three types of help information:
- Help Link – if set, turns the field name into a link
- Short Description – displayed in bold to the right of the field name
- Long Description – shows up in the tooltip when hovering over the field name
To set help information, select the field item under the data definition template and enable Standard Fields in the View chunk of the View ribbon in Content Editor.
Should I use Long or Short Help Descriptions?
Both. I recommend using the short description for stressing important facts about fields. For instance, things that would fail validation or fail a workflow.
Long descriptions should be used for descriptive purposes, for example, explaining the role of the field, the type of data t should contain, and its usage on the website.
Let’s take a look at an example of a Logo image-type field. Here is how the help information would look like for this field –
Short Description: [400 x 200; PNG; 2MB max]
Long Description: The Logo field is used for displaying a company logo. If the field image is missing, a default logo placeholder will be shown instead.
- Sitecore field help information.
Sitecore field help information.
What about the Help Link?
I find myself rarely using this help field, however, it does come in handy in cases when clients have dedicated branding web pages that describe in greater detail regulations regarding types of content. In our example of the Logo field, the Help Link would link to a page describing the Logo guidelines.
As developers, we tend to forget that Content Editors are not as familiar with the implementation, as we are, in fact it is a black box to them, and they are likely even scared to start editing. It is our responsibility to make the editing interface as intuitive as possible and giving Content Editors as much information as possible in Sitecore field help information to help them succeed at their job.