I’m often surprised to discover that many of my Sitecore clients don’t take advantage of some the out-of-the-box guard rails that come with the platform, most notably help text. While the meaning of some fields may be self-explanatory, there are always many more that are non-obvious. This can lead to longer ramp-up time for new content authors, content-based errors, duplicate fields, and general frustration and displeasure with the system.

There are many reasons for this trend. Despite the best intentions of Sitecore platform implementers, some common causes are:

• Time – Quality content object definition and data modeling is complex and time-consuming enough for a robust solution with worrying too much about guides and tutorials. This step often gets left for last which is to say it rarely gets done at all.
• Evolution – Systems evolve over time with new fields frequently added to the mix, often without things help text, validation, and standard values leading to a bit of hodge-podge experience.
• Lack of content author involvement – Content authors are in the best position to define the meaning of the fields they are meant to edit, yet they aren’t always invited into the field definition process as the system is taking shape.
• Inheritance – While it’s tempting to use very granular base template inheritance to drive very common fields like Title, Image, Text, etc, across pages and components this often is an impediment to using help text when the context differs from use case to use case (e.g. when a 1×1 image vs 16×9 image is required in an Image field). What we gain in data template efficiency we give up in context and guidance.

Making sure that fields are well defined requires vigilance in the content object definition process while building an entire platform or just adding a new component. Here are some tips:

1. If building or redesigning a system, do some game-planning in form of a content object definition data sheet that includes a column for Help Text that will serve as a reminder pre-implementation to define this, and by all means, get your authoring teams involved so it makes sense to the people who need to understand it.
2. Use discreet fields on components rather than inherited ones whenever unique help text is going to be required. Consider an Author Experience checklist with reminders to include help text, validation, and standard values.
3. Finally, consider bypassing the use of Short Description for help text since this is, by default, displayed right after the field name in Content Editor which I find affects readability. Instead it is possible to apply some custom code on top of Content Editor that reveals Long Description via a simple tool tip icon, as shown below. The code loops through looking for the Long Description title attribute and in CSS adds a tool tip icon if Long Description is not null. Without this enhancement, the content author would have to know to hover over the title text to see the help text, which is not very intuitive.

By taking the time to ensure that content authors can easily understand the meaning of Sitecore data fields we are facilitating adoption and satisfaction among the folks who use the system the most!

• Author Experience
• Sitecore Hacks