Sitecore Best Practice #10 - Speak English, please

29 August 2011
Adam Najmanowicz

This best practice reminds developers to design the system in a way that once it’s handed to the client, authors are presented with more intuitive interfaces. It reiterates the need for content planning, reasonable defaults and placing the meta-structures in a manner that make sense for marketing executives who are generally not developers.

What is it about?

Limiting the number of roots and giving branches - meaningful names (NOT geeky/ nerdy names) when adding site metadata and configuring settings.

Why should I do it?

We should remember that customers and more importantly, authors are generally not the most technical people and they do not understand or (always) appreciate geek lingo. Our aim should be to provide a content management system with interfaces that are easily understood and not counter-intuitive.

Demo scenario

Author wants to edit footer links that are displayed on all webpages. They open the content editor and try to find where they can change the links. If the settings are stored under the metadata node, it is highly unlikely the author will find the settings as 9 out of 10 times, he is not going to look there for the footer links settings. That's why we should call the node Settings or Common Page Elements or Reusable Elements. We should create a branch called Footer Links (important - do not be afraid to put a whitespace between Footer and Links - admittedly difficult to waste a character but try and forget for a moment that you're a programmer). Now, it is quite straight forward for the authors to find the aforementioned settings.

How do I implement it in my project?

There is not much about implementing here. Just a few things to bear in mind -

  1. We are programmers… we think: “camel case” and “conventions” and “patterns”, but from experience, I can tell you the end users do not think like us.
  2. Authors should be able to find stuff easily without asking us (developers) for help. If our help is necessary, perhaps we could have simplified things a little more.
  3. Do not call nodes metadata, governing, provisioning, allocation, etc. Call them in a way that non-technical people can easily understand what they stores (e.g. Settings, Content sources, Home, Footer links).
  4. Do not use Pascal Casing convention for anything that will be displayed to end users (e.g. do not use FooterLinks, use Footer links).
  5. Do not use words like page, template, etc everywhere. It is enough to call the page Home instead of Home page - everyone knows the Homepage is a page. Same concerns as with templates naming.
  6. When adding a new template field set its 'Title' property to the human-readable text (e.g. MetaKeywords 'Meta keywords').