Building The Goodfrontend Show Podcast Page

Intro

In this blog post, I aim to document my experience in designing, developing, and deploying the podcast page for the GFED website. The post is divided into three major sections, each covering a different aspect of the process. I hope these sections will provide valuable insights and lessons I learned along the way.

The Design Phase

Being a fan of podcasts like 'Software Engineering Radio' and 'The Stack Overflow Podcast,' both catering to software engineers, I found inspiration in their designs. I then adapted and customized those features to suit GFED's specific use case.

The technologies to explore and use for the design and development of the page:

One aspect of GFED's workflow that I find beneficial is that software engineers are given ample time to work on their tasks. We have the opportunity to implement the core functionalities first, ensuring they work correctly, and then later on, we can focus on refactoring and optimizing them. This approach allowed me to thoroughly explore these technologies, familiarize myself with their APIs, customize their configurations to suit our use case, and ultimately optimize them.

Figma

As a software engineer, I used to believe that design tools like Figma, GIMP, Photoshop, and others were primarily meant for UI/UX designers. However, my perspective changed when I met a cadet software engineer here at GFED who was proficient in Figma. He mentioned that he had learned it during the pandemic as a way to pass the time, but he later realized the value of his newfound skill when he used it to design the About page and redesign the landing page.

I invested time in learning the core features of Figma to accomplish most of the design tasks needed for the podcast page. With my existing design sense, a crash course on YouTube about Figma, and dedicated time to learn the tool, I was able to create a high-fidelity mockup design and accomplish the task.

Contentful

For the content management system of the GFED website, we used Contentful. Contentful is quite good being a SaaS-based CMS with robust and developer-friendly APIs.

This is the first time I’ll be using this tool in a project but not the first time I am using a SaaS-based CMS, I enjoyed using Storyblok before for one of our internal training projects -- the FebTrain eCommerce web app. So, I did compare and contrast the two to figure out the core features of Contentful.

Given enough time to familiarize myself with the core features of Contentful, I was able to immediately publish the content needed for the podcast page.

Algolia

The search and discovery tool that I chose to integrate into the podcast page is Algolia. This is the first time that I used this tool in a project, but I have experience working with OpenSearch -- a fork version of ElasticSearch -- so, I thought the way Algolia works might be very similar to it, and indeed it was.

I think Algolia provided a way for software engineers to quickly implement a search and discovery feature to their apps by giving them powerful and developer-friendly APIs.

Netlify

The GFED website is currently hosted and deployed in Netlify, so I don’t need to worry about the deployment. Netlify is a platform that simplifies the process of building and hosting websites, making it easier for developers to create and manage their web projects efficiently.

Using the extreme GitHub flow and Netlify, we have a production deployment that is coming from the main branch and preview deployments that are created on-demand based on every PR (pull request) branch created by our software engineers.

YouTube and Spotify Embeds

Our podcast episodes are published on YouTube and Spotify as of this writing, so upon exploring both of the platforms' features to be able to share their users' hosted content to other platforms, the <iframe> markup is their recommended and straightforward way.

Both YouTube and Spotify embeds enhance the user experience by providing simple and efficient integration of multimedia content within external websites, making it convenient for visitors to consume videos or audio without leaving the webpage.

The Development Phase

Creating the Hi-Fi mockups with Figma

So, I started working on the task by creating the Hi-Fi mockups of the mobile, tablet, and desktop views of the podcast page using Figma.

As a software engineer working on the frontend tier of a web app, frequent enough communication with the team and stakeholders is very important, so having Hi-Fi mockups of the page that you plan to develop will give your team and stakeholders visibility of the things you will need to work on. You can also ask for feedback regarding the design you came up with and the features you intend to implement.

Take note, having an initial design or plan is not a hard rule, this can change after receiving feedback from the team and stakeholders, while you are working on the task, and after your preview deployment.

Coding the mobile, tablet, and desktop views of the podcast listing page

After creating the mockups and receiving substantial feedback, I started coding the mobile view of the page following the mobile-first approach in web development, and immediately deploying it after several substantial commits into the Netlify preview deployment of the GFED website making sure that the build will work and will be deployed without errors early on.

Preview deployment is important and useful for the software engineer in accumulating small wins, building momentum while working on the task, and creating a sense of accomplishment toward the completion of a task. And for the stakeholders, they will have the visibility of the actual progress on a particular task.

While working on the mobile view of the page, I was using hard-coded data and my code is not yet reusable and composable thinking that I can allocate some time, later on, to review my implementations and refactor my code to implement “clean code”.

When a decent version of the mobile view page is done, I started working on the tablet and desktop views of the page -- currently, this is the podcast listing page. This part of development is less on coding and more on thinking about how to make the layout responsive to the viewport size while implementing the desired layout design. After several iterations and modifications making sure that the tablet and desktop view are both working fine, I deployed them once again to the preview deployment of the task's PR (pull request) branch in Netlify.

Coding the podcast details page

I started working with the podcast details page after a working version of the podcast listing page with static data and unoptimized code is up and running live in a preview deployment in Netlify. By now, I can start refactoring some portions of my code to make it reusable and composable because several sections of both pages share the same components, doing this will keep my code "DRY (don't repeat yourself)". During this time, I was still using static data and unoptimized code focusing more on making things work and then refactoring it later on.

Making this page responsive by design is way easier compared to the listing page because several of the reused sections and components were already optimized to be responsive.

Creating the podcast content type and entries on Contentful

As my standard operating procedure when I need to use a new piece of tech, I explored and consume some getting-started documentation first from Contentful to be familiar with the tool's core feature to publish new content, and then immediately try to apply what I know and keep my hands dirty, by doing this I can quickly validate what I already understand and do not about the features.

Contentful's approach in introducing their tool to the users is straightforward, by providing good documentation and user-friendly UI/UX for their users.

Since the integration of Contentful into the project was already done by the previous engineers who worked on the project, all I need to figure out now is the following:

1. How to create the data model for the podcast episode?
2. How to create associations between podcast episodes or other content?
3. How to consume those published data via the GraphQL API?

First, how to create the data model for the podcast episode? This question was immediately answered by the Contentful's documentation. So, I created the Podcast Episode content type then I defined the individual fields' appropriate data type.

Second, how to create associations between podcast episodes, or other content? Now this one I initially thought that it will be hard to configure because this will be related to question number three that I need to figure out, but I was amazed at how simple it is to set up. All you have to do while creating the fields for the data model is to use the built-in Reference type if the field you need requires content from another source.

For example, a podcast episode requires a host field, and then let's say you have a User type already that exists as content. You can simply define the host field as a Reference type that can only accept a User type -- i.e., one-to-one relationship, and voila the association is established. You can also set up the field to associate content from one or more associated content -- i.e., one-to-many relationships.

And third, how to consume those published data via the GraphQL API? Contentful provides a live GraphQL Playground in their platform, so upon publishing the content I was able to create and test the query that I'll use in the client app. Now that the query is ready, I created a service for the podcast page that will query the published podcast episodes as a collection or as a single content. The associated content can be queried at the same time because it was already set up in the content type as a reference.

Implementing search and discovery on Algolia

The podcast page is now looking good because it is now consuming the data stored from Contentful. The search and discovery feature is another feature that I am excited to implement in this task. So, upon searching for the getting started documentation of Algolia, I immediately found several ways of integrating the feature into a project namely InstantSearch.js, React InstantSearch, and React InstantSearch Hooks.

I decided to use the React InstantSearch Hooks because it is the newest and recommended way for Algolia to integrate the search experience in a new project. Like Contentful, the documentation of Algolia is pretty good and straightforward.

1. Picking your dataset for visibility and searchability
2. Fetching data from Contentful and pushing the data to Algolia
3. Setting the relevance
4. Building the search UI

Picking your dataset for visibility and searchability

First, you need to structure your dataset according to the content that you want to be searchable by your user, this is what you call the index. And from this, you need to further identify the field(s) that is only for visibility and the field(s) for searchability.

For example, in a podcast episode, we have the following fields indexed in Algolia:

1. Object ID
2. Title
3. Description
4. Show Notes
5. Date Published
6. Thumbnail
7. Host Details

This set of fields was included in the data indexed to Algolia because of visibility purposes the Object ID, Title, Description, Date Published, Thumbnail, and Host Details are fields needed for the podcast listing page which is the main page that will handle the search and discovery experience. And for searchability purposes, the Title, Description, and Show Notes are chosen because they are the fields that are concise enough to contain keywords that will be useful for the users searching for related topics that they intend to find.

Fetching data from Contentful and then pushing it to the Algolia index

Initially, this process was implemented to be triggered manually, but quickly realized that there is an existing feature from Contentful -- i.e., webhooks -- that publish/unpublish events of a content type can send signals to a custom-made API self-hosted by our GFED website.

The script was originally designed to be triggered by a post-build NPM script meaning every after successful build of the web app on Netlify, it will automatically run and download all of the published podcast episodes but then we realized this is a very expensive process.

Upon exploring the existing solutions, the Contentful platform even offers several webhook templates from different providers such as Algolia itself, Netlify, Vercel, etc... So, I tried Algolia’s webhook template in Contentful but was quickly blocked by the limitation of being unable to fetch content type references on the same request, it was a bummer. But the Contentful documentation again saves the day by showing a custom approach based on the user’s needs, this is what I need to do.

So, I created a Next.js API in our GFED app, that can accept requests from Contentful and then create a child process that will run the script. I thought I was quickly making progress with my task but then a blocker showed up, Next.js API won’t trigger the creation of a child process that will run the script from a request.

After several hours of failed attempts to make this implementation work, I told Kane -- GFED’s founder and director -- my current situation on the task and that I am currently blocked. With just a single question from him, I realized that I just needed to turn around and look in the opposite direction and there I found the solution. This event reminded me of software engineering as a team event. Yes, you need self-driven and talented people to compose a team that can handle the project, but then these individuals need to find a way to work collaboratively as a team. Realizing a new implementation, I refactored the script and embedded the process of fetching, reshaping, and pushing the data to the Algolia index to the Next.js API itself, and there you go, I finally did manage to make it work.

Setting the relevance

The important configuration of podcast episodes index in Algolia that will help with the relevant results is highlighted in the platform as “relevance essentials” -- i.e., searchable attributes, ranking, and sorting.

Searchable attributes

Here, I specified the Title, Description, and Show Notes as the searchable attributes from the podcast episodes index. If the needs arise we can further expand the searchable attributes later on by simply updating the fields that are indexed in Algolia, of course, we need to be mindful of the limitations offered by the Algolia plans.

Ranking and sorting

For the ranking and sorting of the relevant results, we set up the Date Published for now -- i.e., the newest content that is matched to the keyword being searched is prioritized. Soon as the published content grows, we can tweak this feature in Algolia to improve the relevant results found by the users.

Building the search UI

The Algolia search experience is not complete without the UI of course, so I decided to use the React InstantSearch Hooks as per Algolia’s recommendation.

React InstantSearch Hooks is a set of hooks provided by Algolia's InstantSearch library for React, enabling developers to effortlessly integrate powerful search components and functionalities into their applications. By leveraging React's hooks feature, it simplifies state management and offers a more intuitive way to build dynamic search interfaces with search boxes, results lists, pagination, and filtering widgets, leading to seamless and efficient search experiences for users.

Once you’ve configured the Algolia API keys and index to fetch the data, pretty much all you need to do is customize the UI for the relevant results.

The Optimization Phase

Once the working version of all the features specified is implemented, here comes the optimization phase. At GFED, we put a high priority on the Core Web Vitals -- i.e., performance, accessibility, best practice, and SEO -- of every web project we deploy online. Our approach is simple, make sure accessibility, best practice, and SEO are all 100%, and then make the performance green as much as possible.

This part is not a one-time process, instead, it is a continuous approach to achieve our goal of 3 100s and 1 green. Using the extreme GitHub flow and continuous deployment, we can add more features and optimize the page at the same time.

Outro

Finally, this is my take on putting things on paper in terms of my experience in designing and developing the podcast page of our GFED website using Algolia, Contentful, and Netlify. It was indeed an exciting and sufficiently challenging task for me. The podcast page is not yet complete, I think it never will be, because of the workflow that we are using with the project, the continuous and iterative process of improving it -- it is a living project. Though it now has the essential features that our users need to find and consume relevant topics about modern web technologies.

About Me

I'm Billy Arante, a Software Engineer at goodfrontend.dev. Since 2017, I have been an indie software developer, focusing on the web platform. I enjoy creating and contributing to open-source software projects. Apart from web development, I am enthusiastic about machine learning and cybersecurity. Previously, I worked as an IT Instructor at a top coding bootcamp in the Philippines. Although I have a Computer Science degree, I consider myself a career-shifter with around 5 years of technical support experience. I love creating local communities centered around the software engineering career, teaching computer programming to anyone interested, and participating in hackathon events.