How to Recover After a Painful Drupal 8 Migration

If you find yourself here, dear reader, that means you went through one hell of an upgrade process to Drupal 8. I’m sorry you had to go through that. What you now know all too well is that upgrading to Drupal 8 is sort of like what Uncle Ben says to Spider-Man — “With great power comes great responsibility” — except in our comic book where Drupal is the superhero, he says “With great power comes great opportunity to completely fuck it up.”

The good news is that there is a path forward, it gets better, and success is decidedly on your horizon.

Start with a retrospective

Mistakes happen but you have to learn from your mistakes in order to get yourself out of the hole. Gather the team, gather your notes, and spend 90 minutes talking as candidly as possible. You should invite everyone that worked on the project to the retrospective, and no one else. Only people with non-trivial, hands-on experience with the specific project can add value to the discussion. You can share the summary of what went wrong in an email to every other interested party.

Ask why a few times. Don’t just write down a list of every issue you hear, discuss them. Ask why repeatedly until you feel like the root cause of the problem is known. It probably takes 2-3 whys to get there.

Don’t make a plan in this meeting, that comes next, but you have to digest what went wrong first to prevent it from happening again.

OK, now make a plan 

You know what went wrong from your retrospective and, at a high level, you should know what you need to do to recover to best support the business.

First, make a detailed list of all of the issues. Canvas the team and end-users to identify all of the issues. Create a list of everything you feel is a valid issue. For each item, apply a t-shirt sizing level of effort. Is this small (two hours or less), medium (a day of effort or less), or large (days of effort)?

Also rate each item in terms of impact on the business on a scale of 1 to 5, with 5 being hugely impactful to the business and 1 being trivial. Refinements like SEO issues, performance, and anything impacting conversion are likely 5s. Keep yourself honest by identifying the concrete value provided to the business for each refinement before picking the rank.

If needed, don’t hesitate to implement several small refinements during planning to buy your team time to plan for proper recovery, or, if you have your plan in place, to buy you time before working on larger efforts.

Don’t be shy in your planning: Make the big sweeping changes that are needed to get the site where it needs to be. Don't pick and choose, try to be as exhaustive as possible so that you only have to recover once. Technical debt always has to be paid, no matter what, at some point. It’s far better to pay it off now than let it grow.

Managing your recovery while keeping an eye on Drupal 9

Drupal 9 is right around the corner. Take relief in knowing that migrating from Drupal 8 to Drupal 9 is going to be easier than every version upgrade in drupal history. Take a deep breath. The worst is hopefully over. You have migrated to Drupal 8 and that is HUGE. No more looming November 2021 deadline where D7 reaches end of life.

However, make sure that part of your recovery planning includes consideration to ensure your fixes don’t complicate a future move to Drupal 9. Be sure to keep your contributed modules up to date and replace any deprecations used by any of your custom code.

Most importantly, be sure to review our Drupal 9 Readiness Guide in detail to ensure you are following all of the best practices guidelines to be ready.

What to do if your SEO tanked

One common issue we encounter when clients come to us after a failed Drupal 8 upgrade is that their organic rankings are in freefall. Nothing is more painful to a digital marketer than seeing years of accumulate search ranking goodwill vaporize in days. It’s going to take time to recover what you lost, but it won’t take years.

First, run the site through several SEO assessment tools (our favorites are Google Webmaster Tools and Moz). Google Search Console (GSC) will provide crawlability errors including 404s and other technical issues to resolve. In GSC, you can also audit the robots.txt file to make sure that search engines aren't being blocked from pages you want crawled. A paid tool like Moz can make sure that there is no low hanging fruit on the site such as missing H1s, URLs that are too long, and missing meta descriptions. (Although meta descriptions do not directly affect SEO, they should be written to encourage a user on Google to click your link.)

After you’ve gathered data from a variety of sources, combine the results from all the assessments into a single list of refinements, and look for (and prioritize) the fixes that compound. That is, in SEO, you can often fix 3, 4, even 10 issues with a single foundational fix to HTML structure or theme templates. Make those changes right away.

Third, use 301 redirects to save the day — make sure you aren’t using 302s as these types of redirects don’t pass along link equity like a 301 redirect does. Using analytics data and your marketing team’s understanding of important site content, use your CMS’s built-in redirect tool to set up redirects for any links in search results that are 404ing.

Lastly, keep pushing refinements from your hit list through development and encouraging Google to reindex your site. At first, this will be a daily task, then a weekly task until all of the issues are refined. Keywords should be monitored for what users are querying and the content that lives on your site so you can track ranking improvements. While you’re tracking progress on ranking improvements, keep in mind if these keywords are still worth pursuing or if you might be better off targeting other keywords as user behaviors change.

Bonus: perform a detailed audit of the Google Analytics integration and configuration with the site. If you are using Google Tag Manager (excellent!), audit that as well. Pay close attention to goal tracking, custom event tracking, and analytics best practices. Fix any data capture issues immediately — you can’t fix something you can’t verify and sometimes it’s only a simple tracking issue that needs to be fixed.

You will have missed a beat and might miss your goals for the quarter or year, but by executing this plan you will get the site back to a stable, performing state you can build from. Without this work, the specter of not addressing these foundation issues will hamper your digital marketing efforts for years.

What to do if you lost ADA compliance

If your public digital experience isn’t compliant with US accessibility regulations — often referred to as WCAG A, AA, or AA, website accessibility, or ADA — and you are a medium or large business it is only a matter of time before you are the target of litigation. The settlement is always the same: a modest amount of damages owed and a contractual obligation to achieve compliance in a set timeframe (typically 6 - 9 months). It’s far less painful to achieve compliance on your own terms than someone else's.

The first step to recover from lost ADA compliance is to decide your target compliance level. There are three: WCAG A, AA, or AAA. Consult your legal counsel in terms of what level you need to achieve. In general, we think of AA as the most ideal compliance level. This represents a fair effort to make the site easy to use for those with disabilities but balances reality with that old adage that the last 20% of the work takes 80% of the overall effort.

Next, you need to perform a comprehensive audit. This should be a combination of off-the-shelf automated tools and manual testing from an ADA expert to ensure you get a complete picture of the ADA issues. Combine all of these findings into a single list of the issues, and categorize each as editorial or engineering.

Now, prioritize the issues by level of effort (t-shirt sizing like we mentioned previously works great) and impact (again, some refinements will address more issues at once than others). Start with the lowest effort highest impact refinements first, and work through the entire list.

Finally, when all of the refinements are live-run the comprehensive audit again to verify that all existing issues have been addressed and that these refinements didn’t create new compliance issues (it happens). Trust but verify.

And as anything involving ADA compliance consultant your legal counsel. We aren’t attorneys at Third and Grove and while we can help fix your digital compliance, we can’t provide legal advice.

How to fix a poor backend experience

It’s easy to tell if your Drupal 8 editorial backend is well built: If your marketing team complains more than usual, well, it isn’t. You can explain away all of their concerns all you want but the fact remains that if the marketing team is frustrated than the CMS implementation has failed. The most common issue we hear from new clients is that their backend is not flexible for marketers to build pages.

The most foundational issue to determine is if the design of the site was component-driven or not. If the design system was built to support the idea that page templates don’t exist but page components (widgets) do, then you have a framework that will support a path to success. Unfortunately, the inescapable reality is that if the design system was not built to support components, there is very little you can do to address the overall flexibility of the editorial backend without a redesign.

Assuming your design system was built properly, the issue will be primarily on the contributed modules and best practices followed by the development team that built the site. It will be a non-trivial effort, but you can prepare a release — that includes new functionality and a complex release script — that refactors all of the existing content into a component system. The amount of site content and how structured (or not) it is will determine how much of this release can be automated and how much will require manual editorial clean up.

Before working on this cleanup release, define 2-3 core editorial use cases such as the ability to build a landing page for an email campaign. With a clear target state defined, it becomes easy to work backward and determine the technical approach needed to achieve the sought after editorial flexibility. 

Regardless if you need to clean up your backend or recover a drop in your organic visibility, the point is to take your time in planning the recovery process and bringing the right stakeholders together as soon as possible. If you take your time at the beginning of the recovery process, you’ll only have to recover once and then fix your gaze to the future.