Forem: Scott Harrison

Letting the product shape the infrastructure

Scott Harrison — Sun, 29 Dec 2024 20:43:35 +0000

During the holidays, I found some spare time and decided to tackle a project to scratch my own itch. In this blog post, I'll walk you through the problem I set out to solve, the approach I took to build the solution, and how the hosting infrastructure and tech stack were shaped by the product itself. The result was a streamlined workflow that allowed me to move quickly whilst adhering to some of my key engineering principles: readability, performance, and effective use of TypeScript.

As engineers, it's easy to fall into the trap of overcomplicating things—whether by over-engineering a solution or relying on a standardised tech stack that isn't always the best fit for a project. This post highlights how taking a product-minded and infrastructure-aware approach can help solve problems before they arise.

While this post isn't a development tutorial, you can check out the code on GitHub: https://github.com/ScottHarrisonDev/cc-aggregator-game/tree/main.

The Problem to Solve

As a group of car enthusiasts, my friends and I love discussing our dream cars. An ever-changing list of vehicles we would hypothetically own. A while back, we started a game where one person shares a screenshot of a Collecting Cars auction listing, and the rest of us choose a car we'd like to hypothetically own for a year with all expenses covered. The conversation that follows is always welcome, especially since we don't see each other in person as often as we'd like.

What began as a simple game soon became more complex. Initially, I would take a screenshot of whatever listings fit in my browser window. However, I quickly ran into issues:

Occasionally, there would be listings for number plates or motorcycles, which weren't part of our game. I then started applying the "car only" filter.

I had to zoom out to fit more cars into the screenshot.

Advertisements would often sneak in, requiring me to remove them manually in the Chrome Devtools before sharing the screenshot.

What used to take less than 10 seconds to capture and share now took a couple of minutes each day. That's when I realised I could automate this process, or at the very least, simplify it.

The Requirements

At a high level, the goal was to display a page with 12 cars from Collecting Cars for my friends and me to discuss in our group chat. The data would come from the live auctions page of Collecting Cars, filtered for "cars only" and possibly restricted to the UK.

Example Collecting Cars URL which the game will be based on: https://collectingcars.com/buy?refinementList[listingStage][0]=live&refinementList[regionCode][0]=UK&refinementList[lotType][0]=car

Proof of Concept

💡 Note: Fetching data from internal APIs or scraping HTML is generally messy and unreliable, and should be avoided in production applications. It can also incur additional costs for the source website.

The biggest unknown for this project was how to retrieve the data. One approach was to copy the internal API requests to get the raw data. Another was to scrape the page's HTML directly, after making a request to the page as a user would.

After some investigation, I discovered that Collecting Cars uses Algolia for their product listings, fetched client-side. I was able to replicate their request, simplify it, and use Postman to check if I could retrieve a useful response. Sure enough, it worked! I now had access to the auction data in JSON format.

The Build

I initially built a replica of the Collecting Cars page using Astro and Tailwind CSS, displaying 12 cars in a simplified layout. This mirrored the way we'd previously played the game, where I would send a screenshot of a portion of the website.

"Easy Mode"

One issue we often encountered in the original game was that it was too hard to choose just one car from the 12 available, with many people picking multiple options. To address this, I created an "Easy Mode", which limited the options to just 3 cars, making it easier to pick a single one (in theory!).

However, after a few days of playing, I realised that the "Easy Mode" was actually more fun and faster with only 3 options. So, I simplified the game further by making "Easy Mode" the only mode available.

Mobile Styling

Initially, I assumed that the game would mostly be played on desktop, as we used to share screenshots from the desktop website. However, it quickly became clear that users would now access the site directly and share their choices in the group chat, making mobile usage the primary case.

With this in mind, I made small adjustments for a more mobile-friendly design, using a mobile-first approach with Tailwind CSS. These changes were quick to implement and helped maintain a clean, readable codebase.

Infrastructure

As an Astro-based site, the project can be statically generated or server-side rendered (SSR).

One option was to use Cloudflare Worker Pages with the Astro Cloudflare adapter for SSR. However, since the game is only played once per day and there is no on-the-fly logic, SSR wouldn't provide any benefits. Additionally, different users viewing the site at different times could see different car choices which is not ideal. Using Cloudflare, I could introduce a caching layer to store the page for 24 hours, but that would add unnecessary complexity.

The alternative was to lean into static generation. While I have more experience with other hosting providers, I know GitHub Pages supports static generation for Astro projects. The main limitation here is that the car choices would only update when I rebuild and deploy the site.

I briefly considered setting up a Raspberry Pi to run on my local network and trigger this rebuild via a Cron job. However, upon researching further, I discovered that GitHub Actions supports scheduled workflows, allowing me to trigger a rebuild at a set time each day. This solution was simple, free, and preserved the benefits of static generation, while being sympathetic to the source website API (which would only be called once per day, instead of every time someone visits the site as it would be with SSR).

I added the workflow to the codebase and included a footer note to show the last update time (partly to debug, but also so users who come back after missing a day can be sure they are seeing the up to date choices). This has been running smoothly for a few days now and is performing as expected.

Conclusion

In modern web development, it's easy to default to using tools like Next.js or React, paired with hosting on platforms like Vercel, especially for personal projects where we want to rely on tech we already know. However, this can lead to suboptimal solutions, requiring extra effort to fit a square peg into a round hole.

That's not to say you should always use unfamiliar technologies, but rather that the correct tool for the job should be chosen based on the needs of the product, even if it's not something you're already familiar with. Personal projects are the perfect opportunity to experiment with this mindset, which will serve you well in a commercial context.

The source code for the project can be found on my Github https://github.com/ScottHarrisonDev/cc-aggregator-game and you can view the game at https://scottharrisondev.github.io/cc-aggregator-game/

Live Demos: Do they always need to be live?

Scott Harrison — Thu, 22 Aug 2024 22:42:52 +0000

It's happened to the best of us: you're on a video call with the client, showcasing your latest work in progress, when suddenly an unexpected bug appears mid-demo. "What!? This didn't happen before!" you think to yourself as panic sets in. You make a few nervous jokes and promise everything will be resolved in the final release. The curse of the live demo is a well-known and frustrating phenomenon—almost a rite of passage for engineers. In fact, it recently caught out Google as they demonstrated their latest AI product. In the best-case scenario, you have a trusting audience who understands the perils of a live demo. In the worst case, you risk losing their trust or even their business.

In this article, I'll shed light on ways to make your live demos as bulletproof as possible. Not all solutions will work in every situation, but hopefully, this will give you food for thought on how to improve your current process.

Common solutions

Below you'll find some common ways engineers try to improve the reliability of their live demos and the potential trade-offs with each.

Pre-demo run through

Before a live demo, set aside time to ensure your code base is up to date, you have no working changes, and all dependencies and third-party services (like APIs) are available. Give the exact flow you'll be demoing a run-through yourself. Think of this as the technical equivalent of rehearsing a speech in front of a mirror. It offers a chance to spot issues while you still have time to resolve them and helps you practice for a smooth presentation.

While this is an effective way to guard against live demo issues, it can be time-consuming and disruptive to your workflow. The more changes you make to the code base after your pre-demo run-through, the higher the risk of introducing new issues. This means you need to schedule the run-through close to the actual demo time, which reduces preparation time.

Skip the live demo entirely

Some companies prefer a hands-off approach to live demos by not doing them at all. Instead, they show a presentation with screenshots of the feature or share designs with the client. In these scenarios, the client's first hands-on look often comes when they're QAing the feature near the end of the task life cycle.

While this approach may work for some companies and clients, in my experience, most clients want to see the most real-world scenario as early as possible. Screenshots or design files don't instill the same confidence as seeing a functional feature, even if it's still a work in progress. Another downside is the potential for diverging expectations between the client and team. Ideally, the client should see the highest fidelity possible to ensure the work meets their needs, and if it doesn't, the team should find out sooner rather than later.

Let the client have free rein

An alternative to live demos is providing preview or QA links to the client, either during a call or for them to explore independently. This allows clients to examine the feature while it's still a work in progress, giving them time to see if it truly solves their problems and meets expectations.

However, this method has its downsides. Some clients may see it as an invitation for scope creep, generating new ideas they want to include in the release. Other clients might be less engaged and not review the link in their own time, causing the team to miss out on valuable feedback.

Demos as part of the process

One way I've adapted my workflow to counter live-demo issues is to shift left and integrate demos into my development process, rather than waiting until near the end of the task life cycle.

As an engineer, when I complete development on a task and I'm ready for code review and QA, I take the opportunity—while my local machine is fully configured for this new piece of work—to record a video demo of the feature. This could be a Loom with a voice over or simply a screen recording.

This video demo becomes versatile. It allows me to share an accurate representation of how the feature should look and behave with QAs or other team members quickly and easily, as well as being shared in client presentations in place of a live demo. The linear nature of video means less flexibility—you can go back and forth, but you can't change the flow of operations. This can be beneficial when presenting, as it limits the context and scope of the discussion to what's being shown. I've had clients pick up on unrelated background elements during live demos, such as debugging software or test data. The video approach makes it easier to ensure the presentation stays focused. Additionally, when a live demo manipulates data, you may not be able to "go back" or revert changes mid-demo, whereas with video, you can simply rewind.

It's important to note that in my experience, clients expect live demos. Going against this expectation by presenting a pre-recorded video, even if you talk through it live on the call, may not inspire as much confidence as a successful live demo would. The key word here is "successful." As discussed, live demos are less reliable, so this needs to be handled on a per-client basis. One way I often try to alleviate concerns is by following up with a preview link for the client to get hands-on with the feature after the call. This way, if they're truly engaged and want a deeper look but weren't satisfied with the video demo, they can check it out themselves, hopefully boosting their confidence.

Conclusion

While this article has focused on ensuring our demos as engineers are as reliable as possible, it's worth noting that clients shouldn't expect bug-free feature demos during development. Ideally, you'd have a client who understands this and a solid team that can effectively manage expectations. However, this isn't always the case, which is why we need to do what we can to ensure our demos run smoothly. Transitioning from live demos to any of the alternatives presented here may seem jarring, but in my experience, most reasonable clients care more about the quality of delivery than the method of presenting work, especially once a way of working has been established.

Ditch the Tech Test: A Modern Approach to Evaluating Technical Talent

Scott Harrison — Sat, 25 May 2024 21:18:32 +0000

As a software developer with over a decade of commercial experience, I've found myself on both sides of the hiring process over the years. Technical tests are commonplace these days, yet they are a controversial topic. At best, they can be a time-consuming endeavour for all parties involved, and at worst, they have been used to exploit potential candidates for unpaid work. I'm here to propose an alternative approach which aims to reduce the barrier to entry for both candidate and employer, whilst getting a more accurate representation of the candidate's proficiency.

The problem with the technical test

There are various issues with the tech test as we know it. I’ve picked out a few of the main ones below.

Bias

The "suggested" time limit on most asynchronous tech tests is often flexible, not a strict rule. Generally speaking, this means there is a bias towards candidates who have more time to spare. These might be unemployed people, students, or younger people who might have fewer responsibilities, for example. This is not ideal when you want to appeal to the broadest set of potential candidates possible. For instance, a parent in their 40s with two young children could be an excellent fit for a senior engineer position, but they might not be able to spare the 3-4 hours a tech test might take.

Time

As discussed above, tech tests can be quite a time sink for candidates, but they can also consume significant amounts of time from the hiring parties too. Checking out multiple codebases, potentially across various platforms (Github, Gitlab, maybe even the odd zip file!), familiarising yourself with the build tooling, and debugging whether an issue is with your machine or the candidate's implementation, all add up. And that's all before you've even got to the stage of reviewing their actual code.

Accuracy

With the recent advancements in generative AI, the standard asynchronous tech test is less reliable than ever for producing an accurate representation of a candidate's proficiency. AI tools such as Chat GPT, Copilot, and many more are allowing more people than ever to enter the world of software development. AI-generated code is not always easily spotted, especially in a smaller codebase like many tech tests. This opens up the potential for a candidate to pass a tech test without possessing the necessary skills for the role.

While AI has certainly intensified this issue, it has actually been a problem for as long as tech tests have been around. In the same vein as using generative AI to complete a tech test, a candidate could just as well allow a friend, or hire someone more skilled than themselves to complete the tech test. Even excessive use of Stack Overflow and copy-pasting could lead to a passing tech test without a true understanding of the underlying concepts.

Of course, a well-rounded hiring process would include a follow-up review and discussion with the candidate about their approach, which would hopefully flush out the most egregious deception attempts. Ideally, the process wouldn't include this potential waste of time at all.

A potential solution

My alternative to the conventional tech test is a process that every developer is already familiar with: the humble code review. The idea is that as part of the standard interview process, you can allow the candidate 20-30 minutes to complete a code review on a pre-prepared pull request in the source control tool of your choice. Then, meet back with the candidate to discuss their review comments, or even let them do it live with you and discuss as they progress through. You could even have multiple pull requests for different roles or levels. For example, a relatively simple pull request which has syntax errors, whitespace inconsistencies, variable name typos, unnecessary repetition, etc. These would all be great opportunities for a more junior developer to pick out improvements. A senior-level pull request might include more in-depth concepts such as ensuring that functions are pure and testable, components are appropriately broken down, the correct types are being used, and avoiding using loose typing or assertions, for example.

This approach respects the time of both the employer and candidate. It requires similar time commitment from both parties and can be completed synchronously. This closes the feedback loop and streamlines the hiring process, eliminating the wait for tech test results from candidates.

The risk of generative AI, copy-pasting, or outside help is significantly reduced, if not completely removed. This is due to the shorter time expectation and synchronous process, but primarily because it requires the candidate to understand the code and suggest improvements, rather than simply adding their own code to meet acceptance criteria.

The post-code review interview isn't all that different from the standard post-tech test interview, as the concepts are broadly the same. You can ask the candidate to explain their thought process and probe for any missed areas to determine if they don't know the topic or simply overlooked it during the interview.

Conclusion

Like much of software development, there are many solutions to the same problem. The concept proposed in this post presents an alternative to the standard tech test. If your current hiring process is time-consuming and doesn't always give the results you want, then perhaps it's worth trying the code review approach. It could lead to a broader hiring pool and a more accessible, well rounded process for everyone involved.

What homebrew programs/scripts/commands/websites have you created?

Scott Harrison — Thu, 13 Jun 2019 10:32:25 +0000

As developers we often want to increase productivity and streamline our workflow. One of the ways we like to do this is to roll our own tools to 'scratch our own itch'.

I'm interested in hearing what sort of programs, scripts, commands, websites you have created to help out.

What is your default documentation process?

Scott Harrison — Mon, 20 May 2019 17:19:52 +0000

Often when we start a new project we will create a README.md with a brief outline of the project and steps to install. If the project is open source we may include a CONTRIBUTING.md. I feel like there is a lot of stuff that a README.md won't cover.

I'm interested in hearing what you have as your default setup for documentation when you start a new project?

What is that one article you keep going back to?

Scott Harrison — Thu, 09 Aug 2018 22:23:05 +0000

As developers we all spend a lot of time trawling through Stack Overflow looking for answers but what article do you keep going back to and why? It could be something very simple, a tutorial or a comprehensive guide to a specific topic.

For me it's A Visual Explanation Of SQL Joins by Jeff Atwood (coincidentally was the guy who created the Stack Exchange network of sites), whether it's helping out another dev or just jogging my memory i've come back to this article time and time again as it's such a simple and effective way of communicating a relatively hard idea to explain verbally.

Changelog for developers?

Scott Harrison — Thu, 02 Aug 2018 18:27:46 +0000

As you may have seen I recently created a post asking for ways to increase the Bus Factor of a project.

How to increase your Bus Factor?

Scott Harrison ・ Jul 19 '18

#discuss

There were some great responses and it prompted my team to adopt a process where when submitting a code review you select all the other developers as reviewers (not every developer has to approve the request though as this could get tiresome). This should help with knowledge sharing across projects and developers within the team.

A common, and related problem amongst teams of developers working on a project together is keeping everyone in the loop when something changes within the project, be it a code, design or devops related change.

A possible solution I've thought of is sort of a changelog, but for developers not end users. The idea being that there would be a changelog.md file in the root of each project which gets updated whenever a feature is merged to the master branch. The message should be simple but convey anything that may be relevant for a future developer to understand.

For instance, recently a developer made a change to our docker setup and updated the readme.md to reflect this change, however upon picking up the project to add a new feature I didn't check the readme.md and my environment wouldn't work. Rather than looking through commit history or disturbing another developer I could simply have looked at the changelog.md file and seen the following:

31/07/2018
- Now use docker-sync for handling storage in project, details of what you need to change in README.md

This simple message tells me all I need to know before I pick up the project again and get involved. This could be seen as duplication of commit messages but i often find commit messages offer quite technical details of what has changed which isn't always important when you are just jumping back into a project, especially if you aren't touching the part in those commits, however it can be handy to get a one sentence overview of what has changed in more of a high level way.

A colleague showed me this and it seems like this is spot on with what I had in mind: https://keepachangelog.com/en/1.0.0/

What do you think?

How to increase your Bus Factor?

Scott Harrison — Thu, 19 Jul 2018 12:02:29 +0000

Most developers will be familiar with the Bus Factor.

The "bus factor" is the minimum number of team members that have to suddenly disappear from a project before the project stalls due to lack of knowledgeable or competent personnel.

The problem is it isn't always a simple thing to overcome in a development team whether it be someone on holiday, off sick or any number of things that mean someone isn't around to share their knowledge.

What is your approach to increasing your Bus Factor? How do you make sure that the whole team is brought up to speed on projects without reducing capacity too much?