At Industry Dive we rely on newsletters to deliver industry news to our subscribers’ inboxes. These newsletters drive readers to our content and are a valued marketing tool for the clients we work with, making them an essential company product. Unfortunately, the code base supporting them had not been maintained to support this side of Industry Dive’s growing business. While the design and tech teams regularly make updates to web products across the company, our newsletters had not been enhanced in about two years.

There were a few issues from the inception of our newsletter. First, the folder structure was not built to scale effectively which made it difficult for tech and design to add and change features. When they did make updates, they were on an ad hoc basis out of necessity. For this reason, improving our newsletter required more than cosmetic enhancements. The email code needed to be restructured to address most issues. Any improvement, no matter the size, would be a large undertaking.

As these challenges blocked improvements, key product complaints increased and they eventually outweighed the effort needed to overhaul the system. The main goals of the redesign were:

  1. Reducing email file size to prevent email clients from clipping the emails and hiding key content
  2. Increasing maintainability to assist tech and design in making adjustments and adding features
  3. Improving client support to make all reader experiences more consistent
  4. Creating a mobile friendly layout to ensure the email is legible at all screen sizes.

Because this project spanned such a large portion of our product offering we made sure to have a robust testing and quality assurance process. Emails are inherently laborious to test and debug across email clients. Although I was making the majority of the code improvements, I also had a backend developer overseeing my work as well as design team members testing the visual changes.

Nicole Merin’s article Creating a Future-Proof Responsive Email Without Media Queries largely inspired the rebase of our newsletters. The article explains how it addresses our concerns and provides flexibility for varying layouts. This method, the “fluid hybrid” method, uses percentages (fluid) and max-width (hybrid) to allow for a well-designed email at all screen sizes without the use of media queries.

With the fluid hybrid layout for inspiration, I broke the process down into three main sections:

  1. Cleaning up the newsletter directory to identify what files were in use and what to deprecate.
  2. Reorganizing all the active files into a better file system
  3. Converting the newsletter templates and standardizing them across publications

By then end of this process there would be a new, clean file structure with optimized email code.

Screenshots from mutliple newsletters A collection of some of the newsletters enhanced by the code updates.

Cleaning up the newsletter directory

To rebase the file system, I audited the entire folder of more than 100 HTML files. I created a spreadsheet to document the status and functionality of all existing files, which allowed me to determine which files I could deprecate. I had to make sure I wasn’t deprecating any code that was supporting another file or the templates would break, which happened more than I’d like to admit.

By deprecating the old files, we were able to clean out 40% of the directory. While I was deprecating the front-end files, I also commented which features in the backend system could be removed. When a backend developer went in to cleanup our django code, they could get rid of features we no longer use.

Reorganizing our file system

With the decluttered folders, I could make sense of what I was working with, but the structure was not optimal. The naming conventions were random, it was hard to find relevant code and dependencies were not explicit through the organization. To start, I created an empty file system based on how we wanted our templates organized. The base template would live at the highest level and below that would be different templates each in its own semantically named folder with its corresponding stylesheet and includes folder of components.

During the testing phase, we were checking that none of the templates broke by relinking incorrectly. After four phases and extensive testing, I was ready to step away from the file structure and make code enhancements.

Converting the newsletter templates

Thankfully when starting the rebase, I had two key tools to help make the process significantly easier. One was the article outlining how to structure the page; the other was an already converted hybrid template. The working example was perfect to base my code off of.

Rebasing the newsletters

To start, I took the Industry Dive daily, our most frequent newsletter, and systematically deleted code. The hybrid template required significantly fewer tables. I also reorganized code blocks to feed into the hybrid template. This way the premade template and the daily template followed the same structure.

Figuring out how to create standardized spacers was a challenge. Spacers are needed in email design to add margin and padding across email clients. I ended up creating five different preset spacer templates that could be inserted wherever needed.

Newsletter mockup A newsletter mockup with eight different retemplated components.

After rebasing the daily template, I proceeded to rebase all of the included components (editor’s note, news articles, events, etc.). There were thirteen sections to rebase and standardize. For example, many of the daily newsletter components used different conventions for section titles. So, I had to define a standard structure and implement the same code for each.

Next, I rebased our weekly emails. While these had similar issues as the daily emails, they also had underlying design bugs I was able to fix. For example our red section dividers were not working on Outlook but are now supported on all clients.

Rebasing the ads

After the templates were rebased, there was one outstanding issue — our ads. Previously, the ad ops team copied the ad code from past newsletter sends and pasted it into new sends. I needed to define a rollout strategy that would ease and standardize this process under the new and improved templates. I added the new rebased ad code to an ad generator that would take in fields and spit out the updated ad code. This not only helped ensure rebased code but also prevented human error when editing the ads.

Newsletter ad spots The three possible ad spots in our daily newsletter.

Results and takeaways

By the end of the rebase process, we had resolved all of our major issues. On average the email file size is 33% smaller. This not only resolved the email clipping but also gave us room to add new sections to the email. The emails are also now more consistent across email clients and all major layout elements are supported.

The new file structure allows emails to be easily modified. We are already planning new sections to add to improve our product offering. It also allows the user to see a mobile-optimized view when using a handheld device, which makes it significantly easier to read.

In general the rebase process was smooth and improved our newsletter subscriber experience. My greatest takeaway was process and how completing tasks in small, sequential steps can make a project much more approachable. The idea of rebasing an entire newsletter system seemed daunting but by breaking it down and having regular QA feedback, email restructuring turned into a painless experience.