Whether we realize it or not, we all have our own personal best practices and preferences we follow when developing. Below, I've captured some of the things that influence my approach to building out a website using a content management system.
1. Thou shalt start with a strong foundation.
Any building is only as strong as its foundation. This true of a CMS as well. In a CMS, this foundation is the content model. Just this week, our team wrapped up restructuring the content model of a site that we didn't get quite right during the initial build. When we decided on the original content model, it was a perfect example of "you don't know what you don't know." Despite several conversations with the content editing team and reviewing the proposed content structure with them, we didn't quite match the content to their business needs.
As content editors started using the CMS, it became apparent that content model prevented editors from entering content in a way that matched their business and the team was faced with a decision. Should we redesign the content model to better align with the business or should we add on the existing model to handle the new scenarios? Even though the effort was greater for the former, and would result in some backtracking in the project timeline, we ultimately decided it was the right direction. Now that we are live with the new structure, I am so happy with that decision. The content editors are equally happy as we were able to eliminate the need to manually enter content by automating the import of data directly from their source of truth since it now better aligns with the CMS content structure. It took longer, but allowed us to rebuild the foundation even stronger than before and save the content editors a great deal of time in process.
Even though we try to follow our own prescribed "rules," we sometimes fall short and that's o.k. It's important to recognize those situations and adjust. It's never too late to strengthen the foundation as long as you are willing to take a step back and reassess when new information is presented.
2. Thou shalt organize content logically (and keep it organized).
For me, part of the content model is determining how content is organized. Whether you consider content organization part of the content model or not, it is a huge factor in how usable a CMS is.
I support one site that every time I go into the CMS, I have to stop myself from reorganizing EVERYTHING. Maybe the organization made sense at one point and maybe it still makes sense to someone, but to me it looks like the floors of my kids' rooms on any given day. Hopefully you don't have a project like this (or kids as messy as mine!), but if you do - I feel your pain.
If this project has taught me anything, it's - LOCK DOWN THE CONTENT TREE! Some ways to do this are:
- Separate reusable content from navigable (page) content. Isolating reusable content into a separate area in the content tree, such as a "Content Library", is a great way to keep content neat and tidy.
- Create folder types specific to different document types. One easy way to maintain structure is to create a separate type for each document type and limit the placement of content of that type to the appropriate folder or folders. This way it is clear to content editors when they are creating content which type of content goes where.
- Only allow appropriate types in appropriate locations (and don't allow any others).
- Remove all permissions for types which should only have one instance, once that instance is created (home page, site configuration, etc.).
- Build out the initial content structure for content editors rather than leaving them to guess.
Some of these may seem obvious but can be easy to forget in the push to go live. Alas, none of them will help the laundry situation on my kids' floors but hopefully they will help keep the content tree clean.
3. Thou shalt trust thy content editors, but protect them from themselves.
Similar to enforcing the content structure, you can help content editors by putting guard rails in place to help them maximize their use of the CMS while minimizing frustration.
I used to be very much against providing content editors with a rich text editor block/component/widget. I felt it gave editors too much opportunity to fall back into the habit of building with a "page first" mentality rather than utilizing the carefully constructed, well thought out content model (see commandment 1). I thought that if I limited rich text to page copy fields with a pre-determined placement on the page, I could ensure that content editors built out their content the "right" way. What this actually did was frustrate content editors, especially those accustomed to a page first approach to building content. Now, I realize that approach doesn't give content editors enough credit and limits their ability to create the content they need in the way they want. What content editors really need is the flexibility to be creative but also constraints to ensure the integrity of the site.
Some examples include:
- Managing the content structure (see commandment 2)
- Making fields required
- Enforcing a max length on fields which the UI depends on being a certain length
- Using RTE stylesheets to limit the formatting and styles in rich text in order to limit the ability to deviate from the website design and style guide
- Gracefully handling errors, both big and small by:
- Avoiding the display of errors to website visitors whenever possible
- If displaying an error can't be avoided, displaying a user-friendly error message
- Handling missing and/or misconfigured data - even if CMS constraints should prevent this - in order to allow other parts of the page to be shown
- Assuming that content editors will move and rename content, and accounting for this by referencing content by IDs and types rather than paths and names
4. Thou shalt know thy content editors.
I recently had the opportunity to work on a project built by another team - which I always enjoy as it is a great learning experience to see how others are doing things. While working on this project, I saw a feature that really caught my attention. My first thoughts were "whoa, that's cool (or some other word that makes me sound cooler than I am)" and "I wish I had thought of that!". My next thought was "that would be a disaster on any of our team's projects."
As innovative as the approach is and as much as I would love to use it, for most of the content editors our team works with, it would be overwhelming and confusing. I still keep it in mind in case the right project comes along, but I had to recognize and respect that it isn't a good fit for our current editors.
This leads me to another of my CMS philosophies...
5. Thou shalt keep it simple.
For me, this commandment means things like:
- Don't add extra steps for the content editor. Don't make the content editor create a "thing" that goes inside another "thing" unless those things are truly reusable and necessary.
- Don't try to provide too many options or variations in a single component or block. Does the content editor really need 12 background color choices or will 3 suffice?
- Don't create overly complex features. Think about the effort required to test. If it's going to take longer to test than build, it might be too complicated.
A Swiss army knife is great when you are backpacking, but for CMS components doing one thing and doing that one thing well is perfectly acceptable and even preferred in many cases. When given the choice, I'd much rather use a plain old wooden toothpick than one attached to several other sharp objects with which I will likely poke myself in the eye. On one project, I inherited a widget that was so complex I had to read the code to figure out how it worked in order to help the content editor configure it. It had a multitude of options which altered the appearance and behavior of the component so drastically that the variants bore little resemblance to each other. This made it highly flexible, but also highly frustrating to use. It was the Swiss army knife of CMS components, but all the content editor needed was a toothpick.
6. Thou shalt provide instruction text.
Speaking of documentation, even if budget doesn't allow for extensive of documentation (budget is never a limitation though, right?), a little instruction text goes a long way. Help your content editors, and yourself, out by providing context and instructions within the CMS. It's amazing how many questions you can prevent with a few words of guidance. How many times has a content editor asked you "what size should this image be?" Why make them ask? Add a short note on image fields specifying the recommended image size and/or aspect ratio. Additionally, add instructions for page or component properties which aren't obvious or have subtle nuances - make your CMS self-documenting.
7. Thou shalt provide a consistent editing experience.
In addition to including instructions in the back office, providing a consistent editing experience will go a long way towards making content editors comfortable with the CMS. When users are able to anticipate how to enter content, they don't have to spend time figuring out how to enter each field and they can work more efficiently. Consistency can take many forms:
- Using the same type of editing control for fields of the same data type or similar purpose, such as using only checkboxes OR radio buttons for yes/no fields, not a combination of both
- Naming fields the same across document types and components utilizing composition to facilitate this
- Standardizing the configuration of similar components or features
- Ordering fields and groups the same across components and document types
One additional advantage of building consistency into the CMS is that it perfectly positions the codebase for reuse. This, in turn, speeds development and provides for a more stable and maintainable website.
8. Thou shalt not forget about SEO.
This directive and the next one are two of the most challenging for me. I know that I should keep search engine optimization at the forefront when building a website - after all the point of a website is for people to find and visit it. Unfortunately, I have maybe, on occasion, sometimes gotten distracted by other things during a website build and gotten close to launch and thought "oh, shoot - did we include a sitemap?" and "Can content editors easily set SEO tags?"
Luckily, there are a lot of great packages to help you stay on top of SEO available for Umbraco. One of my favorites is SEO Toolkit by Patrick de Mooij. Thanks Patrick for making it easy to handle a website's sitemap and robots.txt, providing a multitude of options for editors to set metadata and a host of other features!
9. Thou shalt not ignore accessibility.
Another area in which I need to work on being more intentional rather than considering it as an afterthought is accessibility. Given that there can be serious financial and legal ramifications of lack of accessibility on a website, as well as very real impacts to your users, it should be a core consideration in the decision-making process when designing and developing a website, but this isn't always the case.
I am currently working on a project for a company which is facing the potential of up to $10,000 per day in governmental fines for accessibility shortcomings on their site. Fortunately, one of my incredible colleagues is a wizard when it comes to remediating accessibility concerns and has been able to make quick work of the challenges identified. He is also passionate about sharing his knowledge and has helped bring me out of the accessibility darkness.
There are also many fantastic resources available for guiding you through the wild world of accessibility, including this fantastic article by Rachel Breeze in the 2023 edition of 24 Days in Umbraco- https://24days.in/umbraco-cms/2023/accessibility/ which also includes quite a few recommendations related to the next topic - performance and security.
10. Thou shalt build with performance and security in mind.
LCP, FID, CLS, CSP, HTTPS, TLS, XSS, HSTS, MIME (sniffing), SRI, IP (filters) - so many acronyms to consider when designing and building a website! Luckily, there are an almost endless number of resources for identifying and handling website performance and security.
This commandment is a great example of "do as I say, not as I do" as very recently I failed on this front miserably. I fell into a couple of traps and we launched a new feature on a site that had pretty terrible performance - so much so that I won't give specific numbers as it is that embarrassing, but suffice it to say that we were measuring page load in seconds. The first trap was the "it will be faster in production with better resources," and the second was "this is just the proof of concept, we'll clean it up later." Guess what - it won't and you won't! Increased resources can only do so much and POC's have a habit of making it into production!
The good news is that we were able to make significant improvements very quickly just by following the basic development rules that we all know but sometimes forget (at least I so very obviously do) - mind your loops and caching! Make sure you aren't making data access calls inside loops or doing other computationally intensive operations, especially ones that don't need to be done repeatedly. Additionally, if you can't eliminate or combine data access that occurs frequently, i.e. for navigation or global page elements, at least cache as much as you can.
The big lesson here is to not be like me - make it a habit to build with both security and performance in mind from the beginning of a web project. It's much easier to apply dimensions to images as you implement them than to go back through the entire codebase to find them all later. It's also easier to remember to put security measures in place if you don't have to remember at all. Build security into the template, starter kit or base code you use when starting up a new project.
These are some of the guidelines I try to follow when building out a CMS. What have I missed? Do you agree or disagree? What drives your decision making when working with a CMS?