At Rock Solid Knowledge, our Umbraco development team has to be consistent and aligned when creating or extending projects, especially when onboarding new developers.
With countless ways to configure the Umbraco backoffice and structure document types, how do you maintain a unified approach while enhancing the content editing experience? Here are some tips to achieve consistent backoffice development as a team.
Starting from scratch can lead to inconsistencies as each developer in your team may approach project setup differently. An unfamiliar project or backoffice makes it harder for your team to collaborate and onboard new developers. Without a consistent starting point, maintaining long-term projects becomes more challenging as custom solutions often vary between projects.
Using a predefined starter kit or dotnet new project template provides a starting foundation for consistency. It ensures common document types, data types, and settings are in place, reducing setup time and eliminating guesswork. A consistent starting point promotes better collaboration and leads to an intuitive experience for both developers and content editors.
Paul Seal's Package Script Writer is a helpful tool that generates dotnet CLI code to quickly setup an Umbraco project with your preferred packages - you can even bookmark and save your settings for later use. Alternatively, creating your own dotnet new project template also offers significant benefits for your Umbraco projects. Both options allow you to standardise your setup, ensuring consistency across your projects with predefined document types, data types, and settings specific for your approach.
By automating repetitive setup tasks, your development team can focus more on building features and delivering value.
Benefits:
Group your document types and data types in "Settings" by using folders for better organisation and structure. In the example below, the document types are organised and grouped as compositions, pages, and elements:
In addition, grouping your custom data types (separately from default Umbraco data types) makes them easier to manage and locate. In the next example below, data types are grouped appropriately for better management:
Organising your document types and data types in "Settings" may not directly impact content editors, but developer efficiency should improve with a consistent structure.
Benefits:
Fundamentals training will rightly encourage you to use helpful names and descriptions for document types. Helpful naming and descriptions gives content editors additional cues about the content's purpose. In addition, a well organised "Settings" section helps developers (especially during onboarding) understand the document type's use and location.
When choosing a name for your document type, it might be helpful to include its purpose. In the example below, document types with a template are suffixed with "Page" to indicate they are website pages for the content editor:
And remember, the human readable name of a document type doesn't have to be the same as the alias. In the next example below, the "Global" prefix is omitted for better readability, as it's redundant in the secondary (Global) content tree:
Use clear names and helpful descriptions to guide developers and content editors about your document types and their purpose.
Benefits:
Choose suitable icons for document types that reflect their purpose to provide users with visual cues (alongside the name and a helpful description) to add extra clarity when a user is creating new content.
However, picking the most appropriate icon for a document type is tricky. Umbraco has a decent selection of icons, so make sure you choose an icon that looks roughly like the type of content it is trying to convey. Take a look at the example below using only default icons. How clear are the different types of content? Does the hierarchy get visually lost?
In the next example below, icons have been selected but are not tailored to the document type, and are deliberately using similar or confusing icon choices. Do they still make sense? What additional context do you gain?
You should also consider singular versus plural icon usage. For document types grouping items, such as multiple authors or multiple pages, the icon should reflect the pluralisation. In the next example below, we have selected appropriate icons throughout, and also accounted for pluralisation of the "Events" document types in the primary (Site) content tree, and the "Authors" and "Article Tags" document types in the secondary (Global) content tree:
When Umbraco doesn't provide you with enough suitable icons, you may want to add your own. Warren Buckley shows you how to add your own custom SVG icons to Umbraco 13 on the official Umbraco YouTube channel. Warren has also created an amazing icon package using Iconoir for Umbraco 14+. Alternatively, Warren also writes about how to create your own SVG icon pack for Umbraco 14+ (Belissima).
Help the user understand what type of content they are working with by using appropriate document type icons.
Benefits:
Once you are using appropriate icons you will need to choose suitable colours for those icons and document types.
Fundamentals training, and many other resources, will encourage you to use different colours to differentiate sections, page types, or functionality. Generally, we favour a reduced set of colours based on the website brand (i.e. blue for NHS, gold for McDonald's, or purple for Umbraco) with a complimentary colour for global content, and a greyscale colour for inaccessible content nodes (and compositions):
When you start to use a lot of different icon colours, the impact and usefulness of colour can become less clear. The content editor will start to question why something is a different colour, and whether it means something significant. Take a look at the next example below with excessive use of icon colours. How obvious is it to understand why the icon colour is different? And what if you run out of colours to choose from?
In the next example below, we have corrected the use of colours for a fictional brand that is primarily blue, with a complimentary colour for global content, and greyscale for folders and groups. It also made sense to keep the RSS feed a recognisable orange colour:
Don't make the content editor think about your choice of colours, as there will be a cognitive shift in their focus from their original task, which was probably simply editing their content.
Benefits:
Organise tabs, groups, and properties with consistency and consideration for developers and the content editing experience when creating your document types.
The majority of websites we create display content left-to-right (LTR) and top to bottom. Based on how the content is displayed in your template, you can better organise your tabs, groups, and properties in your document types.
Content that is most likely to be changed by a content editor should be foremost in the tabs order. A banner title is far more likely to change than the SEO meta description, for example. Groups and properties should be ordered based on their position in your template. In the example below, the article tabs and properties have been ordered with the content editor in mind:
Using tabs can help improve property naming, a challenge familiar to any front-end developer trying to name their CSS classes. Be consistent with naming your tabs across document types (always use "Content" for the main tab, for example). Prefixing property names with the tab name reduces the risk of conflicts and helps developers locate properties easily. In the next example below, the settings for an article document type have been prefixed with the tab (and even group) name to reduce conflicts:
Developers should be able to use naming conventions to quickly locate and work with document types and properties. Content editors should also be presented with an appropriate order that represents the template they are working with.
Benefits:
When using official or community packages for Umbraco, use approved packages only to reduce the learning curve when switching between projects and improve consistency in development.
Use an approved list of packages that you love to install by default, or note those that you recommend for specific functionality in your projects. This might seem excessive, but if you use consistent packages across your projects, you will see near identical implementation and approach from your development team. Older projects using those approved packages will also serve as documentation and guidance for future projects.
You can find some fantastic packages on the Umbraco Marketplace for your projects, including official Umbraco HQ supported packages, and Umbraco community packages.
When you need to install new or non-common packages for Umbraco, you should discuss the possible options as a team, and nominate a member of your team to evaluate the packages. As a team, you can then decide on the best package option and add it to your own approved list for future reference.
Benefits:
Establishing clear standards and guidelines is essential for any Umbraco development team. A consistent approach ensures smoother collaboration, improves onboarding, and enhances both developer productivity and the content editor experience. By keeping these standards accessible, your team can stay aligned and maintain high-quality, efficient development practices. Embrace these guidelines as a foundation for success in your Umbraco projects.
