In this tutorial, I will share some tips that will help you to plan a successful Umbraco CMS project. Starting a new project can sometimes be fun and easy, sometimes the sheer size and complexity of what's being asked can be quite daunting. If you are working on a CMS project for the first time, just understanding where to start and what steps you need to follow is a challenge in itself! If you find yourself in this situation, I thought I would share some tips that I personally find useful in order to build a Umbraco website. If you want to understand my project process when it comes to building a Umbraco CMS-powered website, this is the tutorial for you 🔥🔥🔥

Plan

One of the biggest common pitfalls that I have seen numerous times is not understanding the end goal. What is the clients north star metric? If you are the project lead, you need to take some time to understand what the client's main purpose for building a new site really is. It is important to understand what the key bits on the website are and how the site's going to make money. The main reason for this is time. You will never have enough resources and time to finish everything. When it is your job to plan a project, you need to understand what areas you should prioritise your time on. The features that provide the clients main motivator are the features you should build first. You should assign extra testing time to these areas and make sure they have the most unit tests and test scripts. When a deadline approaches, if the main thing the client cares about has been built, you will have a happier life 😊

From my experience, a lot of projects start with a design/UX period. The people in these teams spend a lot of time talking to the client. At some point, the designs get agreed and the project gets handed over to the development team. In this handover, often the development team will not be given access to the client at all. The development team will have different questions and different needs from the client compared to the UX team. Without knowing what really matters to a client, as a team, it's really easy to focus attention and efforts on the trivial and miss out on delivering the important parts in an exceptional way.

Recently, I worked for a company whose highest priority feature of the website was an enquiry form. The form was very simple, however, it generated most of the leads for the sales team. A partner was doing the development work and forgot to build the form at launch. When they finally built the form, it contained lots of bugs (due to a lack of testing) which resulted in a loss of business. The UX looked great, however, the site wouldn't make money. In the end, the partner was sacked. If they had understood the importance of the form to the business, then they would have built it first and been more vigilant on its testing. If they did a release and the homepage wasn't pixel-perfect, that wasn't the end of the world. If the form broke the company lost money and that was what they cared about. From the partner's perspective, it was important that they 'tested' their new designs and not to worry about existing things. If they had focused their efforts on the important things, they might not have been fired 🤔

Document

After you have the design, you need to build components within Umbraco. You need to take the design and split it down into Umbraco chunks. As we're working with CMS content that can be updated by content editors, we need to think about how the design will be broken into classes, document types, data types, properties, controllers, views, layouts and templates. At this stage you should ask yourself questions like:

  • How many document types will I need?
  • What properties do I need to add to each document type?
  • How can I group properties into similar tabs within the backend
  • Will I use route hijacking
  • What UX elements will need to be re-usable?
  • What needs to be content editable? (My general content rule, is that all content is configurable within the CMS unless I have a good reason not to).

Add your answers into a document, or a spreadsheet. Add all the document types, the properties required on each one and the data type for each property. Add if the property requires validation, is so what. Will the property need placeholder text, if so what. Using an online tool Like Google Docs,m makes it easier for the team to access and update collaboratively. You can use this document as the basis of a spec. Except it to change and evolve as time moves on. I call this document a component catalogue and it details everything I need to build on the project

Refine

Now you have an initial list of things to build, review it. Aim to remove 20% of the components. A good principle to follow is to try to minimise the number of document types you create. This is often easier said than done, though 🤔. The reason why I say aim to remove 20% is that if you have too many document types all with slight variations the backend will be confusing. The fewer document types and components you build, the easier the system will be to use. If you create loads of document types, the content editor will get confused as to which document types they should use and where. I've seen projects with over 100 document types. In these systems, most editors only really use 10 document types and the rest sit there unused as no one can remember what they do.

The more document types you create, the more code you need to maintain. Out-of-the-box, Umbraco doesn't provide a really nice modular approach to breaking up your design into components compared to some other CMS systems. You can not build blocks or components in Umbraco using controllers and code. You can create macros that can be dropped inside a rich text area. Umbraco ships with a few pre-set macros. Macros are OK for simple presentational components, however, if you need to create a component that gets API data or does something more complex, they are limited. When building a Umbraco site, try and identify what components can be built as macros. Allowing the editor to drag in Marcos to arrange the page layout how they want to will result in more re-use.

Another trick in Umbraco to create components is to allow content editors the ability to build document types whose sole use is a component. On any page that you want to allow a content editor to add a component, they build child pages using this document type. From the main page, you can then write some code that reads these child pages and renders them as components. For example, you could design a 'carousel data type' that can be added as a child of any page. On your master page, you can have a section to display a carousel. On page render, you check for any child carousel slide pages. If any child pages of that type are found, you use them to populate the carousel with data. This approach is not ideal, however, it is the best workaround in Umbraco V7.

It's this use of creating modular components that will make your website's future maintenance nice and simple, or a nightmare no one wants to touch with a barge pole. It's a hard balance trying to find a solution that allows editors to create content that also prevents them from breaking it 🤔Try to keep the rendering of your website as vanilla ASP.NET framework as possible. Just because Umbraco is open source, you don't need to try and customise it yourself. If you find you have a requirement that Umbraco can't do, may get the data from an API and put the logic in client-side code!

Code

Every website will have custom business logic. Building a project in Umbraco is very similar to building a normal .NET website. The main difference while working with Umbraco is the routing is slightly different. From Umbraco 7 onwards, I would always recommend using MVC as a no-brainer. With MVC you can very easily create a 3 tiered approach where you separate data from logic. I'm also a very firm believer in being able to unit test my work so I would always recommend a model-based approach to document-type creation like uSiteBuilder.

A lot of developers who haven't worked with CMS systems like Episerver, sometimes scoff at this 'extra' work and fail to see the benefit of model-based CMS development. Strongly-typed objects allow you to deliver sites faster and with fewer bugs. I always recommend you use route-hijacking within Umbraco. Building controllers for your document type will allow you to test your site and make sure it works.

You can build APIs using Umbraco. If you need data, plan which API controllers you need to build. (more info here)

Project Approach

After I have a component catalogue that I am happy with, the next step is to agree with the team on how the project is going to be delivered. If you have a small project, weekly sprints until the project is out of the door is the best route. If you are working on a massive beast of a project that might take one year plus to implement, I recommend you agree on an MVP (the minimum amount of stuff you can show the client to prove you're doing some work) that takes say 3 months to build. Follow this process in chunks, until you deliver everything. An MVP is essential in order to keep the project moving forward and keep everyone happy and motivated 😊

My philosophy for breaking work up and prioritizing sprints is to do the high priority features, the code you have no idea how to write and the hard things as soon as possible. You do not want to have any unexpected shocks down the road when deadlines loom 😱. There is nothing worse than thinking you are nearly done with a project then, at the last minute, realize you have another 4 weeks' worth of dev work to do, due to lack of understanding!

Starting A Project Base

When it comes to getting started with development, a lot of teams use a starter kit and build a website on top of it. I personally don't recommend this approach. Most sample sites have little documentation, have not been built to great coding standards and will contain lots of code that you will never use. I prefer to start from a base site I've created myself that only contains the minimum files and configurations (like the DI set-up and NuGet package). The less code within your project, the less stuff you need to maintain or fix later on 😊

Planning a project is a massive undertaking. You will never work on two projects that are the same. This means that you will always need to create a custom project plan for each new Umbraco project that you work on. On most projects, I follow a very loose and flexible plan. At the start of a project, it's key to understand what's important to the business and to break the project up as much as possible to allow you to provide some resemblance of an accurate estimate. After you start development, prioritizing your hardest tasks first will give you a better chance of completing them on time. If you stumble on a show stopper, the sooner the problem is found the better. i hope this rough guide helps you out in some way. Happy Coding 🤘