Over the years I've read a number of very good pitfall lists for CMS implementations, and after 17+ years in the business I figure the karma cart has come around and it is time for me to contribute to the topic.
Overthinking automation for the content migration
To be sure, automation has a place in content migration for any CMS implementation. In days gone by we often saw initial implementations of CMS solutions, but today almost all CMS implementations are replatform projects in which content is migrated from one CMS to another. The existence of structured content, combined with large volumes of content, seems to demand automated migration, but that is certainly not always the case.
Each CMS stores and manages content differently in terms of granularity and metadata, and inevitably the attribute set for content in a new CMS will have new attributes (specific to the CMS itself), some common attributes, and custom attributes that need to be created. Automation is often valuable when the content is more like data, with extreme granularity and strong typing. Short strings, lookup values, numbers, dates, and other such information is ideal for either a) automated migration or b) integration between the new CMS and an external data source.
Content that is more unstructured, such as articles, pages, images, videos, and comments, is highly dependent on both the content structure and the template designs for the new CMS, and with this type of content a manual migration approach is often the better option. If the very sound guideline of migrating no more than 20-45% of existing content into a new CMS is followed (which is an excellent rule), then the overall amount of content to be ported is reduced from the start. Then, considering that the combination of new content structures and a new template engine will require a fair bit of content adjustment and tweaking to get things looking just right, the manual migration approach is more efficient in the end than to try and write code for automated transfer.
A CMS implementation will typically require both automated and manual content migration. The important pitfall to avoid is to think only one is needed, or that the two approaches can't be used in combination.
Starting content audits too late
Assuming the amount of content will be reduced by half for any CMS implementation (the guideline that you should not port more than 20-45% of your content to a new environment), getting started early with a detailed content audit is critical. The overall body of existing content must be known, and all the metadata for the content must be known as well. In addition to the core content information you'll need to know the connections to the business side of things -- who owns the content, how it is generated and published, and how it is reviewed and approved. It is quite common for a large percentage of business owners to have inherited content from others, and if the content has been around for a while the business owners may not even be aware that they are owners.
So, a detailed content inventory must be established and mapped to business owners, and those business owners must be aware of what they own so that they can make decisions on what content stays, what content goes, and what content needs to be revised.
Not planning for incremental cutovers
Most websites and portals driven by CMS platforms are past their first generation, either because the CMS platform has gone through major upgrades or the site/portal has been replatformed from one CMS to another. Given the complexity of content, the highly integrated nature of CMS platforms, omni-channel publishing, high availability requirements, and many other similar constraints, it is very prudent to design a cutover approach in which sections of a CMS can be turned on in a phased approach. Most environments today simply have too many variables to control to pull off a "big bang" launch of a CMS in which an existing production environment is built out and tested on a new CMS and launched via a cutover.
Consider instead doing things like standing up DAM functionality first, or setting up a forward proxy to split traffic between legacy and new environments. A bit of solid initial planning in this area can greatly reduce cost and risk while getting a new CMS solution up and running faster.
Engaging content authors too late in an implementation
All CMS platforms approach authoring and publishing differently, and while features such as preview, version control, local formatting, and tagging may look the same on paper they can be very different in terms of how they feel to an author. Authors are not focused on exploring the myriad features and functions of a CMS; rather, they are focused on getting content written, staged, reviewed, and published. Over time all content authors develop tips and tricks to get comfortable with the tools they use, and introducing a new CMS platform is a major change. It takes time for content authors to acclimate to a new CMS, and in many cases they can offer valuable insight and feedback to help bolster and validate requirements.
All CMS platforms in use today are pre-built frameworks that can be put into use in test environments very quickly. Content authors should be brought onto the implementation team very early on to let them adjust and to get their valuable feedback.
Not training content authors and developers on core functionality for the new CMS
In some cases CMS vendors will gather requirements and identify scenarios and then build out a base solution as part of an implementation project. The thinking often goes like this -- content authors and developers don't want to see the "vanilla" version of a CMS, nor is it a good idea to expose them to an experience with the new CMS that won't be the "real" one they will see. The very real pitfall in this thinking is that it doesn't let content authors and developers see into the breadth and the design of the CMS, so down the road in the implementation they will be unable to distinguish quickly between core features and custom features.
The suggestion for this pitfall is to conduct full training for content authors and developers so that they understand how the new CMS platform was built. Given this knowledge they will be much more capable of making design decisions for the new CMS, and they will be able to solve problems using process/configuration changes instead of custom development. And, when new features/functions are available in the new CMS, they will be aware of the expanded functionality and can take it into account when solving for the business requirements.
Taking a "lift-and-shift" approach to the content migration
Implementing a new CMS is very complex, and a common line of thinking specific to the content migration goes like this -- we have a lot of content, but we don't have time to sort it all out now, so we'll move it all into the new CMS and sort it out after the cutover. We'll build new templates that mimic the current site design, and shortly after the cutover we'll swap out the templates to show the new design.
This logic rarely, if ever, plays out successfully on implementation projects. First of all it throws out the notion that content targeted for migration should be cut in half from the start. Beyond that it ignores the delicate and complicated interplay between content and publishing templates, how the visual look of content is not simply a function of the template design. Publishing requires templates and the source content to be sure, but it also requires attribute configuration, information architecture, security, navigation, SEO/SEM indexing, and targeting/personalization.
The reality is that "lift-and-shift" migrations bring a significant amount of messy configuration elements with them into a new CMS, and the time it takes to reproduce a visual display of an existing site is far more work than it would seem. Plus, a site has to be tested in two major phases, one for each set of templates (existing "mirror" design and the new design). Far better to get content organized from the start to avoid the complexity and risk of this type of content migration.
Treating beta as a process, not a product
Make no mistake -- running a new CMS in beta is a product management exercise, not just a phase in an implementation project. You have a set of requirements and scenarios to test and validate, and you need end-to-end feedback loops to take in comments and corrections and to push new code frequently. A successful beta of a new CMS solution must account for infrastructure, hardware, system integration, services, and the assumption (from the user's perspective) is that feedback will be reviewed and used to update/improve the product.
Running a beta is part of an implementation project to be sure, but it can't be viewed as a period of time (weeks or months) in which the new CMS runs for the purpose of collecting feedback. The test results and feedback must be reviewed on a regular basis to validate or adjust requirements, and then additional development/QA cycles are needed to push updates to the beta environment. This is fundamentally a product management exercise.
Letting developers over-customize based on programming language bias
All CMS platforms are built on established programming languages. The most common languages for CMS platforms include Java, .NET, PHP, and Python. It is very common for developers to start working with a new CMS, and because the CMS was built with conventions or design choices that seem unusual the developers gravitate toward custom code and whatever their comfort zone might be. It is true that CMS platforms have imperfections in their design, and that some features might be faster to build out with custom code than by leveraging the framework of the CMS.
Custom code gets very dangerous very quickly for a few reasons. First, CMS platforms are extremely complex, and the skills needed to write custom code for them (modules, add-ons, extensions, etc.) require a deep understanding of the CMS design. Second, custom code requires unit, integration, and regression testing. If features in a CMS are built out using configuration options then the testing is already done for the most part and you can focus on functional testing. Introducing custom code brings with it the need for more robust testing to ensure the new code won't cause major issues. Third, custom code always poses a challenge for upgrades, and CMS platforms are upgraded frequently, often multiple times a year.
To be sure custom code is often needed when building out a CMS solution. The pitfall to avoid is jumping in too quickly with custom code to try and build functionality in a smarter, better way. All good CMS platforms have been proven out and tested across hundreds, if not thousands of implementations, and vendors typically have very rich knowledge bases with problems/solution archives. Leveraging the core CMS design and functionality is the best approach for minimizing risk and ensuring viable support in the years ahead.