Sanjay Nair's Blog

The Personal Project to Win Your Next Career Fair

2018-02-25T00:00:00Z

Disclaimer: This article is aimed at beginners to software development or those looking to enhance their personal project experience.

I do a lot of recruiting for my job, mainly for entry level or interns for software engineering. A common question I always get asked about this from prospective new hires is: "How do I stand out?" The answer for me is simple. Have experience building software and be able to confidently and intelligently talk about it.

I think personal projects are a great way that any beginner with a computer and an internet connection can get relevant software experience while building something cool in the process. I always say that all the necessary knowledge to qualify for an entry level developer position is freely available online. I see far too many people I interview who flat out tell me they have no project experience to speak to or they have a hard time coming up with ideas for personal projects to work on.

So instead of repeating my advice to every second person, I thought I would get it down in writing. Here's my go-to, straightforward, biggest bang for your buck personal project that you can put on your resume, show off the recruiters, and build your software engineering skill-sets. If you have a free weekend before your next career fair, I guarantee this exercise will give you a step up over everyone else. 🔑

Two words: Personal Website

Yes! Seems a bit cliche, but building yourself a personal website is a simple and effective way to get real experience in the following areas:

Front-end web development
Continuous integration
Deployment to a public cloud-based platform as a service

Let's see how. 🚀

1. Build the Website and Show off the Code!

Start small. Decide on the content of your website. You can go as simple as a single page with your resume/CV information, or go nuts and add a blog, photo gallery, etc.

Once you're ready to build, pick what you're going to use to build it. Ideally pick something you're not so familiar with so that as you build, you learn.

Keep it basic with just HTML/CSS/JS (Here's a tutorial you can follow for that). Or take it a step further and build it using a popular web framework. Here are a few examples:

VueJS: great for small projects, has a lot of similar concepts to other frameworks.
React: One of the most popular frameworks out there right now.
Angular: Still plenty popular in enterprise.

As you build, push everything to a public repo on Github (get familiar with Git and version control if you need to because you need to). Write a nice README into the repo, outline your development process and giving some simple instructions on how to pull down and run your code.

Next time your talk to a recruiter, you have a new talking point to add to your pitch.

"Here's my personal website I built using ________ . Here's the code in my public Github repo"

Check that box off ✅

2. Create an Automated CI Pipeline

This is a skill some professional developers don't even have a grasp on and a lot of companies are still trying to figure out how to implement. The basic idea is this: create an automated process to build, test, analyze, and publish results about your code every time you update it in Github. This is what's called a continuous integration pipeline ✨.

What this pipeline can do is pretty endless, but here are a few free tools to easily get started:

Travis CI: Easily integrate with your Github repos and have jobs trigger every time you push code. Useful if you need to build or test you code and extensible for when you need to deploy it (read about that further down).
CircleCI: Another free CI tool that lets you run automated tasks every time your code updates.
SonarCloud: Have your code scanned and analyzed for quality.

"Here's the continuous integration pipeline that builds, tests, and quality scans my code automatically every time I make update to it in Github."

At this point, the recruiter is already going to remember you.

3. Deploy Your Website to a Public PaaS

So often the last but more crucial step to really finishing a project is skipped. If you don't deploy your website somewhere, then how do you expect to show it off to anyone outside of your localhost?

Github pages is an easy and free way to host a static website through a free, public Github repo. It's where I host my website! If you took the HTML/CSS/JS route in step 1, this might be a good choice.

But if you really want to take it to the next level, using one of the many free cloud service provides to host a site is a great way to get the same cool effect while gaining an extra skill under your belt. It can the final punch that really knocks the recruiter's socks off.

Sign up for a free account on Heroku. They provide support for deploying apps written in all kinds of languages. Go through the steps to manually deploy your app to their platform and enjoy your website, now publicly available for everyone to see!

"My site is deployed to Heroku. I have it running on one of their free-tier dynos. The site deploys automatically every time I push new code to the repo."

If you've knocked all that out, here are some extra credit steps to try out:

Hook up your CI pipeline to Heroku so that when you push new code to Github, it will not only run through a build and code scans, but it can then automatically be deployed live without you having to do anything else!
Buy a custom domain name through Namecheap or another domain provider and set it up to route to your hosted website. Now you have a personalized and simple URL to get to your site while learning about setting up DNS entries.

As you go through this process, you will struggle through a lot of new and unfamiliar concepts. But if you really take the time to dive deep into something with a goal in mind, you will come out learning a whole lot and with a pretty cool product to show for it.

I didn't go into detail about how to do any of the steps I mentioned on purpose. Click through some of the links I included. Go through the getting started guides. Make some mistakes and spend a lot of time banging your head against your desk in frustration. At the end of it all, you should feel confident in the skills you executed to make it happen.

My hope is that no up-and-coming developer should ever feel lost when trying to find ways to expand their experience and skill sets. Hope this helps you get started. Good luck.

Getting to Know Terraform

2018-03-16T00:00:00Z

Every few weeks or so, I try to spend some quality time getting to know a concept or technology outside my core proficiency of web application development. About half a year ago, I had the chance to dabble in some cloud infrastructure management. It was, to some degree, restricted to a lot of repetitive, manual tasks on a tiny corner of the platform. With the rise of the big cloud providers like Google Cloud Platform, AWS, and Azure, it seemed like being comfortable with the fundamentals of moving through those systems was becoming an ever increasingly necessary skill to have. However, with my limited experience, I didn't feel like I could confidently say I had good experience in "cloud infrastructure management."

Fast forward to today, and an article on the front page of Hacker News caught my eye. It was called Terraforming 1Password, written by the founder of Agile Bits, the company behind the popular password manager: 1Password. It outlined the process that the company went through to convert their system of "Infrastructure as code," moving from the AWS proprietary provisioning tool called Cloudformation, to Terraform: an open source solution built by Hashicorp. You might be familiar with some of their other products: like Vagrant and Vault. Give the article a read when you get a chance, it's a good one.

I thought back to experiences manually provisioning and deploying cloud infrastructure. I thought Terraform seemed to make all those past pains go away. I figured learning something about it would move me in the right direction of getting properly familiar with some cloud infrastructure fundamentals. And it did! But in some ways I didn't initially expect.

Getting My Feet Wet

Before I started, the cloud service provider I was most familiar with was Google Cloud Platform, at least from the basics of how to work with the tools and what suite of services it offered. However, I figured to get the full understanding of what Terraform had to offer, I needed to spend some time getting familiar with some other cloud service providers. So I signed up for a free tier of all three cloud services.

GCP seemed to have one of the better trial offerings (at least at the time of writing this piece) with a year long trial including $300 of free credit to apply to various services. AWS follows a slightly different model where each month, you can remain in a free tier by staying below a threshold of usage for each of their services (which is set at a plenty generous level for a hobbyist). Azure has a mix of both models where you get $200 in credit monthly, a selection of services free for a year, and the rest billed at a free usage tier.

With that, I had a multi-cloud, basically free, playground to start automating some infrastructure.

Getting My Hands Dirty

With my cloud playground up and running, I started following along with some guides and the Terraform documentation offered by Hashicorp. The Terraform: Getting Started course offered by Pluralsight was also a good place to start, since it was based mainly on Amazon Web Services with a sprinkling of Microsoft Azure. Soon enough I was up and running, or more specifically, spinning up and immediately tearing down infrastructure between GCP and AWS.

Terraform follows a modular design principle with a well-defined set of abstract components to play with, each with different flavors based on what concrete cloud environment it corresponds to. All the specifications are done in the Hashicorp configuration language, which itself is easy enough to pick up. One struggle I faced was the open endedness of how Terraform files come together. It seemed the best way to go about it was to simply copy and paste existing examples from documentation and modify it to your needs.

I started by copying some of the basic examples I found online for each of the cloud providers. Spinning up a nano instance on EC2 or GCE, putting it behind a simple load balancer, maybe provisioning a database service, making sure it all worked together properly, and promptly tearing it down.

Then I ventured into the wild west of making these provisioned components work between clouds. I thought this was actually pretty cool. With Terraform, I could break down the barrier the industry thrives on: getting customers tightly integrated within their ecosystem of products and making it pretty hard to break away from them. It was one of the reasons I was so isolated to GCP before I started this whole exercise. I do have to say though, even with that extra utility, it was still enough of a struggle to get an AWS lambda function to publish messages to Google Pubsub. I didn't try much after that, opting to spending my time writing this instead :). I'd be interested in what other examples could be thought up, that could take advantage of the best parts of each cloud and bring them together.

Additionally, it was a different experience to run code that had an external impact, that if I messed up, could potentially cost me a good chunk of money. Every time I ran terraform apply and got an error, there was a small part of me that feared some rogue process was left unattended, eating through my free tier of usage and piling on some uncapped cost onto my credit card. Or some malicious agent stole my access key and was provisioning compute instances to mine Bitcoin. So is the nature of working with cloud providers: having the potential to scale your app fast means having the risk of having to pay for it…fast. Luckily, I was very liberal about running terraform destroy and keeping my environments clean. My costs never went above a few bucks a month. Keep those secret keys out of Github!

Moving the Needle Forward

After spending a few good days with Terraform, here are my takeaways.

What I learned:

Terraform is a very powerful tool that is highly customizable, interoperable with your platform of choice, and easy enough to pick up and run with. It may be overkill for your hobby projects, but certainly a fun way to get a better handle on cloud infrastructure management.
On the surface, most cloud providers offer similar services. However, the actual experience of working with them can be drastically different form a developer and operations perspective. Some examples include authorization and IAM, API offerings to access platform features, and customizability of offered components.
There a lot you can do in the cloud for free or with a few bucks a month. Consider taking your personal projects to the next level by taking advantage of what's offered for free.
I gained a lot more familiarity of with the plethora of services offered by cloud providers. Every, single, cloud has that that one marketing page with a hellacious number of services. Going through and getting using some of them actually made the whole collection as a whole less intimidating.

And some questions I pose:

My definition of what a "Full Stack Developer" seems to be expanding further and further out. Does it still mean "I am proficient from the backend to the frontend of the application stack," or should it include the scope of devops where you not only own the application but also the infrastructure it runs on?
Are cloud service offering going to continue to diversity with different service providers, consolidate into fewer into the few and big, or will we mix and match them as we need like programming languages today? If tools like Terraform are any indication of what's possible, I'd wager on the last option.

As you can probably tell, my journey into learning this one tool expanded out into an unexpectedly broader study of navigating cloud service providers and getting to know their pros and cons. However, this exploration might not have happened without a unique, open-source tool like Terraform available to tinker with and learn from.

So for that, go sign up for some trials of AWS or GCP or Azure or whatever you fancy today. Play around with some Terraform scripts, and learn something new while having some fun.

Asynchronous JavaScript

2018-04-01T00:00:00Z

Callbacks vs Promises vs Async/Await

JavaScript and many other programming languages support an abstraction known as asynchronous execution. What this means is when you want to execute some task that might return some data in an unknown amount of time, JavaScript lets you predefine what to do once that data does show up while continuing to run the rest of your program.

An example of this might be calling an HTTP service which might take 500 milliseconds to return a value with a good network connection or 5 seconds if the network connection is poor. Instead of locking up your program for up to 5 seconds, JavaScript just lets you say what to do when the value does come back, continues on its merry way, and only handles the response when it has to.

As of the date I am writing this article and the current ECMAScript8 specification JavaScript follows, there are 3 main ways to write these asynchronous abstractions. Here's a brief overview of each.

Each abstraction presented below will achieving the same result: call a function that does an asynchronous task like calling an external service over a network that returns some data and prints that data to the console.

Callbacks

Callbacks are the original and usually simplest abstraction to first learn about asynchronous programming. Basically, when you have a function that you want to run asynchronously, you include a "callback function" as one of the input parameters. When the function finishes what it's doing, it will "call back" that function with some data if its successful. You can extend this by passing more than one callback function, usually one to handle when the function succeeds, and one for when there is an error.

Example in JavaScript:

console.log("Start of my code")
const myCallbackFunction = function(dataReturned) {
    console.log("Got the data!")
}

// Simulating a service call that takes 50ms to return data
// Then calls the callback function
setTimeout(myCallbackFunction, 50);

console.log("End of my code")

Should result in the following output:

Start of my code
End of my code
Here's the data returned

Run it here!

What's good: A pretty simple abstraction for beginners to learn and easy to debug.

What's not so good: So-called "callback hell" when you have to chain together multiple asynchronous operations, your code can get messy and unreadable fast.

Promises

Promises are a step up from callbacks in that instead of having to predefine how you want to handle the result of your asynchronous operation up front in the same context, you use what's called a Promise object to represent your request and handle it when and where you want.

When you call an asynchronous function that supports Promises, it will immediately return a Promise object. This object can be in 1 of 3 states: pending, resolved, or rejected. Each of these states means the request is still being worked on, the request has been completed with a result, or the request has failed with an error respectively.

You can pass the promise object around, and when you are ready, you can use the built in .then function to handle the result or the .catch function to handle an error.

Example in JavaScript:

console.log("Start of my code");

function getMyData() {
  return new Promise(function(resolve, reject) {
    // Simulate getting the data successfully
    resolve("Some data");
  });
}

getMyData()
  .then(myData => {
    console.log("Got the data!");
  })
  .catch(error => {
    console.log("something went wrong");
  });

console.log("End of my code");

Should result in the following output:

"Start of my code"
"End of my code"
"Got the data!"

Run it here!

What's good: Give's you a lot more flexibility to organize your code. You can chain together multiple asynchronous operations with .then functions easily. Good library support to handle parallel groups of asynchronous operations.

What's not so good: Doesn't provide any runtime advantages like better performance compared to callbacks. Really just cleaner code.

Async/Await

The async/await abstraction is the new and shiny for developers looking to be on the cutting edge of JavaScript development. It is only recently getting standard support in browsers but has been available to use through transpilers like Babel. This is due mainly to the fact that async/await is really just syntactic sugar over the existing Promise abstraction.

What async/await lets us do is write asynchronous code in a more linear fashion than callbacks or Promises. If a function is going to do an async operation, you just slap an async keyword in front of it. Then when you call the async function, just provide the await keyword before it, and your code will run as if it is waiting for the function to return before running the next line of code.

This should be nothing new for anyone programming in a language that is written with the expectation of synchronous execution like Java or C++.

Example in JavaScript:

function getMyData() {
  return new Promise(function(resolve, reject) {
    // Simulate getting the data successfully
    resolve("Some data");
  })
    .then(function(data){return data});
}

async function getMyAsyncData(){
  console.log("Start of my code");
  
  const myData = await getMyData();
  console.log("Got my Data! ", myData);
  
  console.log("End of my code");
}

getMyAsyncData();

Should result in the following output:

"Start of my code"
"Got my Data! " "Some data"
"End of my code"

Run it here!

What's good: Let's your write asynchronous code linearly with no new constructs like callback functions or Promise object syntax. Since it's just Promises under the hood however, it's easy to debug and is by far the cleanest way to keep your code concise.

What's not so good: As of writing this article, support for async/await is still picking up speed, both in tooling and with developers. It's supported by all the major browsers and Node, however backwards compatibility still requires polyfills. Check on its current support here.

Final Thoughts

If you're working with JavaScript, you're going to encounter one of these abstractions at some point. More likely, you're going to have to write some asynchronous code yourself. A good rule of thumb is if you are writing new code, start by using Promises, as they lend themselves to future maintainability the best. As the codebase grows, your code should stay cleaner comparatively than if you used callbacks. If you see places where the Promise syntax might be a bit too verbose, try to swap it out for async/await. Keep in mind what browsers/platforms you are building for and add transpilers or polyfills as necessary.

What is CICD — Concepts in Continuous Integration and Deployment

2018-05-06T00:00:00Z

Modern software moves fast and demands more from developers than ever. Tools and concepts around CICD help developers deliver value faster and more transparently.

You might have heard the term CI, Continuous Integration, CICD, or Continuous delivery. It's a concept that goes by many names but covers the same basic ideas. In short, it lays out some practices to follow in order for the code you write to more quickly and safely get to your users and ultimately generate value.

While this idea might seem best suited for software written for enterprises or some capital venture, I bet that by the end of this article you will find CICD to be a valuable practice whether you're building enterprise applications at scale or simply trying to get your personal project up and running.

CI : Continuous Integration

The CI part of CICD can be summarized with: you want all parts of what goes into making your application go to the same place and run through the same processes with results published to an easy to access place.

The simplest example of continuous integration is something you might not have even thought of being significant: committing all your application code in a single repository! While that may seem like a no-brainer, having a single place where you "integrate" all your code is the foundation for extending other, more advanced practices.

Once you have all your code and changes going to the same place, you can run some processes on that repository every time something changes. This could include:

Run automatic code quality scans on it and generate a report of how well your latest changes adhere to good coding practices
Build the code and run any automated tests that you might have written to make sure your changes didn't break any functionality
Generate and publish a test coverage report to get an idea of how thorough your automated tests are

These simple additions (made easy with tooling that will be mentioned later) allows you, the developer, to focus on writing the code. Your central repository of code is there to receive your changes while your automated processes can build, test, and scan your code while providing reports.

CD : Continuous Deployment

Deploying code can be hard. If you've ever been jamming on building a project for a while, shifting your mindset to getting it ready to be deployed can be jarring.

One of the best things you can do to avoid this, much like other things in software, is to automate it! Make it so that your code gets automatically deployed to wherever you or your users can get to it.

There are many freely available tools to let you do this easily. One popular example is Travis CI, which integrates directly with Github. You can configure Travis to automatically run CI tasks like unit tests and push your code to a hosting platform like Heroku every time you push new changes to a branch.

Examples of CICD in Real Projects

You can find examples of CICD being used all over the place; you just need to know what to look for. Usually, its as easy as finding some colorful badges linked at the top of a Github README.

ReactJS

The React JavaScript framework developed and maintained by Facebook has a great example of a robust and high visible CICD pipeline. If you visit its Github page and click through the badges displayed at the top of their README, you can get an idea of what type of automated processes they run their codebase through. The Coverage badge links to Coveralls, which is a tool to display unit test coverage reports. You can click on the CircleCI badge which shows a history of all the builds automatically run against Pull Requests submitted by contributors. If you click on a build, you can even see every step in the CI process and how their pipeline is configured.

Homebrew

If you do any sort of development on MacOS, then you've probably at least heard of the popular package manager Homebrew. It uses TravisCI with coverage reporting on codecov.io. Check out Homebrew/brew on Github and scroll down to the Contributing section to find those same familiar badges.

TensorFlow

Machine Learning and AI related projects have been rising in popularity for a while now and I think Google's TensorFlow library has had a lot to do with that. TensorFlow is an open source Python framework for building ML and AI applications. Their Github README is decorated with the same familiar badges but with an additional twist.

Since TensorFlow is a cross-platform tool that can run on CPU and GPU hardware, the maintainers have set up multiple pipelines to build and test the tool on different operating system platforms and CPU/GPU configurations. Their pipelines are built using Jenkins.

If you're looking for more examples, I would start by looking through what's popular on Github. Chances are, if there are a lot of users and contributes to the project, there's probably some publicly visible CICD process in place to help the project scale with the number of developers involved with it.

Consider some open source tool or library you might be using right now. See if you can track down if it uses CICD in some way. If not, maybe that's something you could contribute back to the project!

Next Steps

Now that you hopefully have a better idea of what CICD actually is and how it is woven into the way modern software is built, you can take those considerations into mind when working on your next project. Always give some thought to what processes could be automated when changes are introduced. How can information about the project be more transparently communicated to the team working on it? How can the project more efficiently be delivered to its users?

I encourage you to pick up a CICD tool and introduce it to one of your existing projects or use it when you're spinning up that next personal project.

Tools:

Convoluted Convolution

2018-05-29T00:00:00Z

This post was originally published when I was in college in 2014. I was enrolled in a digital design class that dealt with designing and implementing digital circuits through software. It was one of the first posts I shared publicly where I tried to write about something I learned about and work on.

This past semester, I had the opportunity work on a couple of pretty interesting class projects. Normally, I would say my classes are not usually the prime source of creative projects, and therefore would avoid writing about them altogether. However, a couple of them stood out to me as valuable learning experiences. Each gave me insight into an aspect of technology that I was worth discussing in detail. The first project I would like to discuss was working with the VHDL programing language and FPGA hardware to implement a one-dimensional time domain convolution application. The project gave me some intriguing insight into the differences between working with hardware vs. software platforms. On the surface, the project was easy. Implement a custom circuit to perform one-dimensional convolution with a constant kernel size of 96, 16 bit elements. If none of this is making sense, read this to get familiar with what convolution is all about.

An implementation of this application in software could be condensed down to these short lines of code:

// 1D convolution
int y[outputSize];
for (i=0; i < outputSize; i++) { 
	y[i] = 0;
	for (j=0; j < kernelSize; j++) { 
		y[i] += x[i - j] * h[j]; 
	}
}

In one dimension, the kernel is represented as a constant array of values that are repeatedly multiplied over an input array in the same manner as a sliding window. The output can be described as a signal that has been “convoluted” by the kernel.

At a high level, our hardware implementation would have three parts:

An input SRAM that would hold the input signal to be fed into the convolution routine
The application datapath, which in this case would hold a 96 element wide multiply-accumulate tree to perform the convolution in parallel
An output SRAM that would store the results returned from the datapath

How this would go in software

Designing this application in software, even for higher dimensional inputs, seems trivial. A few lines of code and a user-friendly interface (which might end up taking more time to build) and you’re done. You have a vast library of languages, function libraries, data structures, and tools by which to develop, debug, and publish the application swiftly and cleanly. What you write is purely deterministic and would never act randomly unless you explicitly wrote such a feature in. If something isn’t working right, then it was your fault. Simply copy the code I provided above into your language of choice, debug, test, and you’re off.
Welcome to the world of hardware

The previous description had been my experience for the past 3 years when building applications in general. This is not to make it seem easy (it is certainly NOT easy), but rather to contrast it with my experience developing the same application in hardware. Software always works the way you have specified. Whether or not you made a mistake is your problem. Hardware sometimes works the way you specified. However, it will always be victim to the laws of physics over which we sometimes have no power.

First, a bit of background on the development process. This application was to be first designed in software with VHDL. My group members and I could thoroughly test every single circuit we designed using hardware simulation software (ModelSim) to provide some assurance that our digital design made sense before we put it onto a physical circuit. The design would then be synthesized onto a Xilinx Vertex4 FPGA housed on a Nallatech PCI Express card housed in a server room somewhere on the University campus. If that last part sounded a bit weird, it was meant to. We had not physical access to the hardware the application would run on. Our design was synthesized into a “bitfile” that had to be remotely uploaded to the server. Then, through software, we would configure the FPGA with the bitfile and run the circuit with some input. The only feedback we could get was from the software output on the console we were interacting with. The process was basically design, test, synthesize, run, and pray everything worked on the board. You might say, “That was the point of all that testing you did before you ran it on the FPGA, right? To make sure execution on the board worked perfectly!” Well, partially. Unlike software where, if all variabilities are known then a piece of code should always run as tested, hardware can be victim to the randomness of the physical world.

Metastability — how physics beat us

Without boring you with the fine details, certain aspects of our circuit had the potential inherent randomness built into them. Connected sequential circuit elements always expect each other to only change on a rising (or falling) clock edge. When connected elements like registers are running off different clock frequencies, this guarantee disappears and some really weird stuff can happen. Output signals can resolve to incorrect values and flood your circuit with errors. This phenomenon can be attributed to metastability, or the unpredicatable “third” state of digital signals. Anyone who has worked with even the simplest digital logic (even just in theory) knows that a single bit out of place could destroy the logical soundness of a system.

Without the proper precautions and countermeasures, running a circuit on the board would result in perfectly non-deterministic results. And the worst part, there was basically no way for us to debug the problem. First, because the problem itself could be changing on each execution. Second, the physical hardware was physically inaccessible to us. Third and most importantly, the software simulation we used could not simulate metastability. Even if our simulation worked perfectly, it was no guarantee the circuit would work on the board.

Our Project Results

When the project was finally completed, it had been thoroughly tested and run on the board with no errors. After the files had been submitted and when the due date came around, we ran the project again…but there were quite a few errors this time. Not a single line of code had been changed. The simulation still showed 100% on all tests. Yet the circuit consistently passed only 96% of the tests on the board. We still have no idea why this happened, and we never might. So I learned how unpredictable and mysterious hardware design can be sometimes.

Conclusions

Metastability is nothing new to hardware design. Plenty of solutions have been created to overcome this issue in circuits with multiple clocks to ensure they perform deterministically (at least with a significantly high probability). Yet, these ideas really got me thinking about the primitive building blocks of computing as a whole. Our physical world is said to be deterministic and governed by the laws of physics (don’t mention quantum uncertainty because I still need to do more research before tackling that topic properly). We build digital circuits with the assurance that a 1 would be a 1 and a 0 would be a 0 exactly when we want. But no matter how tightly we constrain the physics, when even the slightest element of variability enters the scenario, everything falls apart. If a single bit on the input to a flip-flop changes a nanosecond too early, our deterministic assumptions disappear. We may build our circuits around this random possibility, but that is exactly the point I found to be important: when we design in hardware, we must overcome physics itself.

Software is deterministic because it runs on hardware that was designed to function perfectly 99.999% of the time. It is designing directly with hardware that has made me acknowledge this fact and come to appreciate how different software design is as its core.

How to Make a Q&A Chatbot With Machine Learning

2018-07-11T00:00:00Z

This article will teach you how to write your very own Slack chatbot that answers simple questions using some basic machine learning tools. Most of the more complex stuff around natural language processing and math behind creating machine learning models is mostly abstracted out, leaving room for us to easily build a finished product in a pretty short amount of time. If you're looking for a simple and effective way to get a semi-intelligent bot answering questions on Slack fast, then this guide is the one for you.

If you want to skip to the finished code, check out the link to the Github repo here or at the end of the post.

Edit 10/27/19

Because the library I used (Botkit) had a few critical security vulnerabilities and I couldn't get the latest version of the library working, I switched over to the Slack RTM API. The below code examples should work just fine, but if you're interested in using the latest version of the code, check out the example repo at the bottom. Link to Pull Request with all code changes.

Some Setup

This guide assumes you have basic knowledge about Node development, as this will be the main tool we will be using to build with. You're also going to need the following installed and working on your machine. I'm usually most productive in a unix-like terminal environment, aka bash. Here's what else you will need:

An installation of NodeJS with the npm package manager. I used Node v10.1.0 with npm v6.1.0 when writing this, but any relatively recent version should work (like v6 and up).
A Slack workspace that you have administrative rights in. If you can't find one, just make a new one. This is the playground where we will be developing and testing out bots capabilities.
A code editor. I'm a big fan of VS Code.

Once you have your Slack workspace open, go to any channel and click on the settings gear icon. We're going to add an app to our workspace.

Search for bot and add the Bots integration.

Add the configuration and give it a name you like. This will basically create a special type of user in your workspace you can send messages to, just like any other user. You can change the name and icon of the bot later, but what we need now is the API Token value that get's generated. BE SURE TO KEEP THIS VALUE SECRET. If someone gets access to this, they get free access to read and post messages in your workspace.

Keep that value handy. We're going to use it soon as we start writing some code.

Time to Code

Basic bot setup

To get something set up, let's start by getting some boilerplate code out of the way. The following npm commands should get the basics set up.

# Starting in the directory where your code is going
npm init -f
npm i --save natural botkit@0.7.4 dotenv

Notice the three libraries we will be using.

natural: Provides basic text processing and classification functions
botkit: A wrapper around the Slack API to easily write programs with integration with Slack
dotenv: Let's us manage environment variables in a file for local development and testing

From there we can start writing some code. Let's start by making sure we can connect to Slack using the API token we set up previously. Create a file named .env and paste in the following contents replacing the part after the = with your API token.

SLACK_API_TOKEN=

If you are using something like git to maintain your code changes, make sure to add .env to your .gitignore file so you don't accidentally push it somewhere others can see it!

Next let's get to the real code. We're going to start with some simple setup to make sure we can connect to our Slack workspace using the API token and with some help from the botkit library. We can start with the an index.js file like this:

const botkit = require('botkit')

// Load our environment variables from the .env file
require('dotenv').config();

// What are the types of chats we want to consider
// In this case, we only care about chats that come directly to the bot
const scopes = [
    'direct_mention',
    'direct_message',
    'mention'
];

// Get our Slack API token from the environment
const token = process.env.SLACK_API_TOKEN;

// Create a chatbot instance using Botkit
const Bot = BotKit.slackbot({
    debug: true,
    storage: undefined
});

// Function to handle an incoming message
// In this example function the bot will just reply with "got it"
function handleMessage(speech, message) {
    console.log(speech, message);
    speech.reply(message, "got it");
}

// Configure the bot
// .* means match any message test
// The scopes we pass determine which kinds of messages we consider (in this case only direct message or mentions)
// handleMessage is the function that will run when the bot matches a message based on the text and scope criteria
Bot.hears('.*', scopes, handleMessage);

// Instantiate a chatbot using the previously defined template and API 
// Open a connection to Slack's real time API to start messaging
Bot.spawn({
    token: token
}).startRTM();

The code above should be simple enough to get your bot up and running. You just need to execute node index.js, and your bot should connect to the Slack API and show up as "Active" in your workspace. If you send it a message, it should reply back with "got it". You could also modify the code to have the bot respond with whatever you like.

Adding some machine learning

Now that we have the basic setup done, we can start to add some intelligence to our bot. Since we're aiming to have our bot answer questions, we need to take a bit of an open ended approach. Not everyone asks questions the same way. So we need a way to match different questions or phrases coming in with what topic they're associated with, and then give the appropriate answer.

Like I might ask: "What time is it?" while you might ask the same thing by typing "Give me the current time." Both phrases could be matched to the topic of "current-time," so we can't just use strict equality in our code. We are going to employ some machine learning to do this fuzzy matching.

The first thing we need for this is a training data set with a pre-populated set of phrases, associated labels, and appropriate responses or answers. The training data format will be JSON that outlines some phrases and keywords that represent a type of question and a single answer that the bot should respond with when it sees a question like those phrases or keywords. For example, here's a training data set with only two topics, each with a set of possible phrases, and an appropriate response:

{
    "self": {
        "questions": [
            "introduce yourself",
            "sup",
            "hi",
            "hello"
        ],
        "answer": "Hello! I'm a chatbot tasked with answering your questions! `Beep, Boop` :robot_face:"
    },
    "world": {
        "questions": [
            "what is the world",
            "answer to the universe and everything"
        ],
        "answer": "42"
    }
}

Put this in a file called trainingData.json in the root of your project.

Each group of questions and answer has a label. This is how our bot will try to classify all the input it receives and figure out how to respond.

Now let's add some code to consume the data and train a classifier we can later use to intelligently match and respond to questions. We can create a simple function to read our trainingData.json file and convert it into a JavaScript object we can read from.

/**
 * Function to easily parse a given json file to a JavaScript Object
 * 
 * @param {String} filePath 
 * @returns {Object} Object parsed from json file provided
 */
function parseTrainingData(filePath) {
    const trainingFile = fs.readFileSync(filePath);
    return JSON.parse(trainingFile);
}

Then we can load our training data using the function like so.

// Load our training data
const trainingData = parseTrainingData('./trainingData.json');

Next up is creating what's called a classifier to consume our training data and create a machine learning model to later make decisions to incoming questions based on what it has learned. Basically, given the set of phrases and responses we provide, the model should be able to extrapolate what response to provide to a phrase it sees as similar to one it has seen before. If you want to learn more about what exactly a classifier is in the context of machine learning, check this out.

We're going to use a library for this. So start by importing the natural library we installed earlier and create a new LogisticRegressionClassifier at the top of you file.

const NLP = require('natural');
// Create a new classifier to train
const classifier = new NLP.LogisticRegressionClassifier();

Next we need a function for the classifier to be able to ingest training examples. In this case: what questions (phrases) match up to a given answer type (label).

/**
 * Will add the phrases to the provided classifier under the given label.
 * 
 * @param {Object} classifier
 * @param {String} label
 * @param {Array.String} phrases
 */
function trainClassifier(classifier, label, phrases) {
    console.log('Teaching set', label, phrases);
    phrases.forEach((phrase) => {
        console.log(`Teaching single ${label}: ${phrase}`);
        classifier.addDocument(phrase.toLowerCase(), label);
    });
}

Now that we have a way for our bot to learn some examples of phrases it might see and classify them appropriately, we need a way for it to handle sending back a proper reply.

Since our training data includes an answer for a set of example phrases under a label, we can use it to have the bot send back the same reply. So if our chatbot sees an incoming message that looks like "sup", based on our training data, it should classify it with the label "self" and send back the answer associated with that label: "Hello! I'm a chatbot tasked with answering your questions! Beep, Boop :robot_face:". Look back at trainingData.json if you need to see that example again.

One thing it considers is the fact that our classifier's guesses will usually not be perfect. Each guess will have a different confidence value associated with it corresponding to how confident the classifier is to matching a label to the phrase provided. As a result, we need to put in some logic to only give a response if the classifier is pretty certain it has the right guess of how to label the input phrase. If not, we basically respond with "¯_(ツ)_/¯ don't know what you're talking about. I'm not trained to respond to that."

That's a lot of explaining, let's see what our function to interpret incoming text looks like.

/**
 * Uses the trained classifier to give a prediction of what
 * labels the provided pharse belongs to with a confidence
 * value associated with each and a a guess of what the actual
 * label should be based on the minConfidence threshold.
 * 
 * @param {String} phrase 
 * 
 * @returns {Object}
 */
function interpret(phrase) {
    console.log('interpret', phrase);
    const guesses = classifier.getClassifications(phrase.toLowerCase());
    console.log('guesses', guesses);
    const guess = guesses.reduce((x, y) => x && x.value > y.value ? x : y);
    return {
        probabilities: guesses,
        guess: guess.value > (0.7) ? guess.label : null
    };
}

Notice where we check if guess.value > 0.7. What this says is that if our classifier does not match a label with a confidence of at least 70%, then we say we didn't find a match. Whatever message came in didn't match anything we trained our classifier to respond to, so we return null and our ¯_(ツ)_/¯ response.

This is like if someone asked you "What time is it?" you know exactly how to respond because you learned what that question means and how to get the answer. If someone game up and said "Blargen Flostel Bhigba" chances are you never learned how to respond to that, so you'll probably throw up a ¯_(ツ)_/¯.

So now we need a function to match up that label with the answer that corresponds to that label. Let's modify our handleMessage function to do this. Instead of sending back the same reply to everything, let's interpret what the message was, then use the label our classifier generates to provide the appropriate answer based on our training data. If our attempt to interpret the message didn't yield a result, the bot can simply reply that it didn't understand.

/**
 * Callback function for BotKit to call. Provided are the speech
 * object to reply and the message that was provided as input.
 * Function will take the input message, attempt to label it 
 * using the trained classifier, and return the corresponding
 * answer from the training data set. If no label can be matched
 * with the set confidence interval, it will respond back saying
 * the message was not able to be understood.
 * 
 * @param {Object} speech 
 * @param {Object} message 
 */
function handleMessage(speech, message) {
    const interpretation = interpret(message.text);
    console.log('InternChatBot heard: ', message.text);
    console.log('InternChatBot interpretation: ', interpretation);

    if (interpretation.guess && trainingData[interpretation.guess]) {
        console.log('Found response');
        speech.reply(message, trainingData[interpretation.guess].answer);
    } else {
        console.log('Couldn\'t match phrase')
        speech.reply(message, 'Sorry, I\'m not sure what you mean');
    }
}

Last up, let's bring it all together by calling all the functions we just created and the existing ones we have to get our bot up and running. Notice the code at the bottom is basically the same, except we've modified the handleMessage function to be a bit smarter this time around.

// For each of the labels in our training data,
// train and generate the classifier
var i = 0;
Object.keys(trainingData).forEach((element, key) => {
    trainClassifier(classifier, element, trainingData[element].questions);
    i++;
    if (i === Object.keys(trainingData).length) {
        classifier.train();
        const filePath = './classifier.json';
        classifier.save(filePath, (err, classifier) => {
            if (err) {
                console.error(err);
            }
            console.log('Created a Classifier file in ', filePath);
        });
    }
});

// Configure the bot
// .* means match any message test
// The scopes we pass determine which kinds of messages we consider (in this case only direct message or mentions)
// handleMessage is the function that will run when the bot matches a message based on the text and scope criteria
Bot.hears('.*', scopes, handleMessage);

// Instantiate a chatbot using the previously defined template and API token
// Open a connection to Slack's real time API to start messaging
Bot.spawn({
    token: token
}).startRTM();

Taking it for a spin

Let's see what our bot can do! Go ahead and run node index.js in your console in the root of your project directory. If all goes to plan, you should see your bot injecting your training data examples and start up waiting for input.

Head back to Slack and try to ask it to introduce itself!

Ask it something else you trained it to respond to!

If you ask it something it hasn't been trained for, expect an appropriate response.

But you could always train the bot to respond to that by adding it to your training data! Just create a new label and add some questions and an answer you'd like the bot to respond with.

Conclusion

I was going to write some extra stuff about how to deploy the bot somewhere and potential ideas for enhancements, but this post has already become longer than I anticipated. I never did get around to writing that follow up, but in the meantime, please comment with your feedback. Was following along easy enough? What skill level are you at with Node development or ML concepts? Also don't forget to share the cool bots you create!

Other resources

Complete code example available here: Nirespire/FAQBot

Udacity Intro to Machine Learning: intro-to-machine-learning--ud120

The Wide World of Databases

2018-08-27T00:00:00Z

Working in software, it's easy to get caught up in all the latest and greatest technologies and frameworks. Every other week there seems to be a new JavaScript framework that "solves" all your problems. However, one of the most fundamental pieces of any non-trivial application is how you store and retrieve your data, i.e. your database.

In this post, I'll go over some of the most common types of databases you might encounter in modern software development and what makes them unique.

Relational Databases

Probably what they're teaching at school.

The trusty relational database (RDB) is usually the first thing you encounter if you take the traditional, academic avenue into software development. This is very much on purpose, as shown by the StackOverflow Developer Skills Survey from 2018, four out of the five most used database technologies by all respondents were RDBs (excluding MongoDB).

If you're planning on taking your learned skills from school into industry, you're probably going to need to know something about RDBs.

RDBs are designed around the mathematical concepts of relational algebra. Everything you can do in a RDB can be modeled with a relational algebra expression. The SQL query language is designed after these expressions and provides a pretty simple interface to interact with data. Efficiently organizing your data requires following the rules of normalization or the normal forms. Each entry is identified by a primary key with data structured into tables that can be joined together.

RDBs have been around quite a long time (back in the 1970s) and are very good for general purpose data access patterns for applications. As a result, they are often the go-to choice for general application workloads for the web and enterprises.

Why they're good:

Commonly used around industry with wide support
Very efficient and fast if following well established practices for modeling data and systems administration
Great for simple application workloads like writing and reading small chunks of data on well-defined identifiers or keys
Usually ACID compliant, meaning they provide strong guarantees about the integrity of your data

Why they're not so good:

Typically, relational models of data are hard to change once they're heavily in use, limiting effectiveness when building fast-changing POCs
Running through very large sets of data for aggregations can be very inefficient
Performing "fuzzy" queries when a key or search query isn't well-defined
Horizontal scalability isn't usually built into the implementations and are usually achieved through some higher level abstraction layer. You might find real-world implementations to be very monolithic as a result.

Some Examples:

MySQL — Free, opensource, used widely at Uber
Postgres — Free, opensource, also widely used in industry
SQLite — Free, opensource, stores all its data in a single file, commonly used in embedded applications like smartphones
IBM DB2
OracleDB

Document Databases

You've heard of MongoDB, right?

Document databases usually fall under the umbrella of NoSQL databases. They typically don't follow concepts of relational algebra in their design and you usually don't interact with them through SQL. The rules as to how to define a data model are a lot more flexible. Each entry in your database is a document, which is usually just a JSON object stored as binary data with an associated key. You can group your documents into logical collections where there's no strict requirement about how the data in each collection or even adjacent documents can look. It works well for simple, flat data that is read and written in simple patterns.

Why they're good:

No predefined schema means it is really easy to get up and running when building POCs or test applications
Use-cases outside of simple reads and writes, like search queries
Easier to horizontally scale through multiple nodes since collections and documents do not share any strict data relation
Storing simple, contiguous, independent entities of data

Why they're not so good:

Complex queries that filter on multiple values across documents or collections
Data that has a lot of relationships and links. Check out this article for more about that
Many implementations do not provide ACID guarantees

Some Examples:

MongoDB — Opensource, probably the most recognizable brand in document databases
Couchbase
Elasticsearch — Opensource, used for common search workloads
RethinkDB — Opensource, realtime database for online applications

Key Value Stores

Basically a really, really sophisticated hash map.

Key value stores or KV stores are commonly used when your data needs are simple enough that you can boil them down to querying for a key and getting your data value back. No relations or extra logic needed. This pattern can be applied to persistent data on disk, or temporary stores used as caches for increased performance and availability. Once again, KV stores fall under the NoSQL umbrella of databases because their storage and access designs don't follow any relational models.

Some example use-cases include Redis, which is a popular in-memory KV datastore commonly used as a caching mechanism in applications. Since it stores all its data in memory by default, it gets the benefits of performance while lacking any guarantee the data will be preserved after it is shut down. For example, if an application is commonly querying a disk-based database for the same few entries, it might get them from disk once, then store those entries by key in Redis so it could retrieve them faster next time. If Redis goes down or the application restarts, the only cost would be a slower first retrieval of the data.

Why they're good:

Super fast performance
Highly scalable
Great as a supporting datastore for application workloads to improve performance

Why they're not so good:

Inefficient at anything other that looking up data by keys
Bad performance on complex queries or searches
In-memory implementations are not designed to be the primary datastore for applications

Some Examples:

Redis — Popular in-memory KV store
Memcached
AWS DynamoDB — Amazon's managed, highly scalable KV store in the cloud

Column-Oriented Databases

So, imagine a relational database…but sideways.

To explain column-oriented databases (yet another NoSQL set of databases), let's first see how data is stored on disk for this kind of database vs. the more common, row-oriented design. Below is a comparison of what data stored in a row-oriented vs column-oriented system would look like on disk:

The performance of a database operation is largely depending on physical proximity of data, whether on a spinning hard disk or between nodes in a cluster. The immediate side effect of organizing column data close together is that queries over a full row become less efficient in favor of queries over a full column. Each row typically has a row key, however the data is queried using the column values rather than keys on the rows. Some implementations group column key's or column qualifiers into column families to more easily group similar sets of data.

As a result, column-oriented databases fall into some very specific application use-cases, mostly dealing with online analytical processing (OLAP) workloads rather than typical transactional workloads.

Why they're good:

Great for big data and data analytics applications
Running aggregation querying over very large data sets
Efficient storing and querying of timeseries data
Highly scalable depending on the layout of the data in the system
Compression of data entries per column since the data is all structured the same

Why they're not so good:

Inefficient for querying over a small, disparate sets of rows
Online transaction processing (OLTP) workloads, typical for user-facing applications, are very inefficient
Performance is highly dependent on key and data layout design. Google provides their own analysis tool just so customers of their column databases can better design their keys

Some Examples:

Google Cloud Big Table — Google's column oriented database as a service
Amazon Redshift — Amazon's version
Apache HBase — An open source alternative to the proprietary implementations

Graph Databases

We're all connected

The Graph we're dealing with here is the computer science version, i.e with one composed of vertices and edges. Graph databases take those same concepts and rename them to nodes and relationships. Simply put, graph databases represent data in nodes that are linked together using relationships. An obvious real-world use of a graph database would be for modeling social networks, where nodes are users and relationships are the links created between users like becoming friends.

With these storage capabilities comes all the benefits that has come from the mathematics around graphs, including efficient graph traversal and analysis algorithms. If you find yourself thinking about your data like a network of connected nodes, a graph database would probably provide the easiest abstraction with plenty of sophisticated methods of interaction.

Why they're good:

Good at representing complex relations between data
Can deal with constantly changing relationship structures between data

Why they're not so good:

Can only query data based on anything other than relationships
Slow at storing and querying large amounts of data for OLAP applications
Not efficient at running algorithms on the data that are not optimized for graph data structures

Some Examples:

Neo4j — A lot of what you will read about graph DBs will usually end up here

Misc

I did want to mention CockroachDB and Google Cloud Spanner. Both are pitched as a database with a relational model that comes with all the benefits of ACID compliance while also having potential to scale to massive workloads. Spanner was introduced by Google as the first publicly available, managed service on the Google Cloud Platform to offer such stellar availability and performance from a ACID compliant RDB. CockroachDB came onto the scene not too long after as the opensource alternative that advertised the same benefits. Both are ultimately RDBs with some significant enhancements to enable some horizontal scalability that would otherwise not be straightforward with other RDB implementations.

Conclusion

With these quick summaries and reference links, I hope you are better informed about the varied world of database solutions out there. Try your hand at getting one of them up and running and using it for your next personal project. Get familiar with the nuances of working with data between the different paradigms. Reconsider where and how the online data you see everyday is stored and retrieved.

The Wide World of Software Testing

2018-10-01T00:00:00Z

In a previous post about continuous integration and deployment, I alluded to the practice of constantly putting code through various tests and making the results visible, whether within a software team or to the public for an opensource project. In this post, I want to dive a little deeper into what "testing" actually is in the context of writing quality software. Specifically, I'd like to shed some light on the different types of testing and how they can help you write better software.

Unit Testing

Absolute unit

Unit testing is the lowest level of testing. It's about as simple as you can get when testing software, but don't discount its value. A few simple unit tests can go a long way to keep your codebase robust, bug-free, and maintainable over time.

A good way to explain unit testing is by example. Say we have a function written in pseudocode like so:

function addNumbers(a, b) {
    // Makes a network call to validate inputs
    validateInputs(a, b)
    
    return a + b
}

The unit test might look something like this:

test("addNumbers adds two numbers correctly") {
    // Mock the network call
    mock(validateInputs).toReturn(true)
    
    result = addNumbers(1, 2)
    assert(result equals 3)
}

Notice how we're only testing for what this function does and nothing else. Any dependent operations, like a network call, are "mocked" or functionally faked to resolve to a predetermined result. If your application runs inside a framework of some kind, it will usually be ignored in favor of just running the unit of code in question. In general, we'd like a test only the unit. In this case: the function and it's expected behavior.

As a result:

Unit tests should be pretty lightweight and run fast since they don't depend on anything external to the unit of code being tested
The only way they can fail is by changing the unit of code they are testing
It is usually necessary to augment unit tests with more comprehensive testing methods to ensure complete confidence in your code working as expected

Integration Testing

The whole kit and kaboodle

While it's great if the different pieces of our codebase work correctly alone, it's also essential that they work properly together as a complete package. This is where integration tests come into play. Unlike unit tests, integration tests will typically bring surrounding frameworks and multiple internal components together to ensure they are working as expected. While this still might not include interactions with external resources outside the codebase being tested (like networked resources), integration tests typically give a more complete picture of how your whole application will actually run.

Below is a piece of an integration test written with the MockMVC framework for a web application API written in Java.

@Test
public void integrationTest_getMyResource() {
    this.mockMvc.perform(get("/myResource/123")
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.id").value("value"));
}

The test spins up the web application, the various internal application components, simulates one of its API endpoints being requested, and asserts that the expected output is produced. In this case, we assert that when requesting the myResource endpoint with an id, we get a JSON payload back with that same id.

Some resulting features of integration tests:

They are a bit more heavyweight and typically run slower compared to unit tests since they depend on multiple software components running together
They give a better view of the "correctness" of your software beyond the code you write, but also for things like how libraries and frameworks affect how your application runs
It's about as good as you're going to get with confidence that your software will run correctly without actually running it and testing it manually

I want to disclaimer a bit here before continuing. In most cases, unit and integration testing will probably get the quality of your software to where it needs to be. Beyond that, more complex types of testing will deliver value only if your software exhibits a certain level of complexity or demands a high degree of scale. As a result, you will find the below flavors of testing mainly in enterprise or other professional settings. However, there's plenty of value to have awareness and know when they might be effective to introduce into a project's development.

End to End Testing

From the front to the back

End to end (or E2E) testing comes into play when the software solution you are delivering has multiple, independent parts that may not be able to be represented in a single codebase. As a result, it is necessary to run tests with real instances of the applications to ensure that input on one end results in the expected output on the other end.

Since, by nature, E2E tests typically involve multiple codebases and applications, an example of an E2E test case can't really be represented by a simple code snippit. Rather, we could present an example software architecture and provide some examples of E2E tests scenarios we might like to execute, manually or through automation.

Consider the following architecture:

Some E2E test cases might include:

When a button is clicked on the UI, a request is routed from the first app server to the second server, processed, and returned to the UI
When a form is submitted on the UI, a corresponding entry is created in the database
When a button is clicked on the UI, and the second app server encounters an error, the first app server can gracefully handle it without disruption to the user

The same principles can be applied to any level of complex architecture.

As a result of this open ended bound of complexity:

There really isn't a right or wrong way to do E2E tests, as long as validations are being made on appropriate inputs
E2E tests are commonly performed manually since the value of automation can be nullified from the sheer number of changing parts of the system without tight integration with a codebase

Performance Testing

"Run like the wind Bullseye!"

Some applications are built with a very high volume workload in mind. For that reason, it would be necessary to validate that software can handle the demanding workloads by simulating them and analyzing the results.

For example, a web application could be expected to handle hundreds of requests per second while performing complex data transformations. A performance test might spin up an instance of the application and simulate high volume conditions while monitoring various application metrics like resource utilization and response time. The passing criteria for a performance test might be that every request is fulfilled within a defined time at peak load and computational resources are not exceeded.

Load Testing

"I'm givin' her all she's got Captain!"

There's a subtle distinction that needs to be made between load testing and performance testing. In a sense, load testing might be considered a subset of performance testing. Load testing is a method which evaluates the performance of a system under high load. You might want to understand the characteristics of the system, like CPU usage or memory, while it is being constantly hammered by a massive amount of requests or computations.

While performance testing might look directly at metrics like response time, load testing is more like a litmus test to ensure your application can hold up under stress. Think of it like a stress test for your application to make sure it doesn't fall over under a demanding workload. That way, you can have some confidence that when your application is under a high load in production, it will hum right along without crashing.

User Acceptance Testing

If we want users to like our software, we should design it to behave like a likeable person. -Alan Cooper

The user acceptance test or UAT might just be the ultimate of all tests mentioned here. It throws automated validations and calculated metrics out the door and instead puts the final judgement of the "correctness" of your software in the hands of its user. A UAT usually happens right after or before the delivery of an application to production. An end user is presented with the application and is encouraged to use it as they would normally. The acceptance criteria is pretty simple: does the software do what it's supposed to do for the user according to the user?

You could think of all the other types of testing we discussed here as servant to this final type. Ultimately, everything we do to make quality software is some way in service to the users of that software. We might have the most robust unit tests, ran our app through the battery of the hardest performance and load tests, and executed every E2E scenario imaginable. But in the end if the user doesn't get what they need, it's all pointless. However, we should still hold ourselves to a high standard of software quality. Eventually, that benefit should reach your users through less bugs, faster and more frequent delivery to production, and more flexibility to add features.

I hope you are more informed about the varied options when it comes to testing your software. If you haven't already, I encourage you to check out my post on Continuous Integration and Deployment where software testing plays a central role.

A Light Introduction to AI Safety

2018-11-02T00:00:00Z

I was recently listening to an episode of the podcast This Week in Machine Learning and AI, featuring professor Nick Bostrom. He is the author of a book I recently read called Superintelligence, which explores the potential consequences of artificial intelligence that surpasses the capabilities of human beings by orders of magnitude. Bostrom is also a member of the Future of Life Institute which seeks to steer humanity through a safe course into the future along with the rapid pace of technological advancement.

On the podcast, Bostrom highlights the relatively brand new academic area of AI Safety. It is a really fascinating topic which I feel is becoming increasingly relevant in the modern age, and I figured it was a topic that might not be familiar to many. So here is the beginners crash course of what AI safety is and why you should probably care about it.

A (Very) Brief History of AI

Contrary to what news media might make you think, the concept and implementation of AI is not a brand new, modern concept. It has existed since the 1950s, with academics like Marvin Minsky laying some of its foundational concepts. While mostly mathematical, these early concepts led to the creation of specialized areas of AI research including but not limited to:

Knowledge Representation: Also known as "expert systems," this area sought to collect and represent "ontologies" or absolute truths in various areas of human knowledge

Natural Language Processing: How to build abstractions and algorithms for computers to consume, process, and interpret language

Computer Vision: How to take raw visual information and translate it into "features" or add meaningful interpretations to it

And many, many more…

Digital implementations in these areas through various techniques resulted in systems that were significantly superior to humans in their specialized areas of expertise. Some famous examples include IBM's Deep Blue, which beat world champion chess player Gary Kasparov at his own game. While Deep Blue was more of a brute force implementation which computed many thousands of moves ahead and picked the statically best move, more recent achievements such as DeepMind's Alpha Go overcame much greater statistical complexity of playing a game of Go through reinforcement learning techniques.

A relatively recent product delivered directly to customers that implements concepts from computer vision and reinforcement learning is car manufacturer Tesla's autopilot system, which can provide basic automated driving capabilities to their line of electric vehicles. Look at Google's Duplex system for smartphones that, through the use of natural language processing and deep neural nets, can effectively mimic a basic phone conversation.

There's no question that with today's technology and techniques, it's possible to develop a specialized system that could learn to perform a narrow set of tasks, sometimes even better than a human.

The Possibility of Artificial General Intelligence

The technological achievements of AI are incredible, considering the pace at which the theory translated into implementations are delivering real world value. There literally are multi-million dollar businesses built on these technologies. However, these solutions could still be considered too specialized to pose any real threat. A chess playing robot is probably not posing any threat to humanity. Something that has still not been achieved (at least not publicly), is the concept of an Artificial General Intelligence or AGI. Also known as "Strong AI", I defer to the Wikipedia definition to summarize the idea:

Artificial general intelligence (AGI) is the intelligence of a machine that could successfully perform any intellectual task that a human being can.

This is the AI of science fiction: the kind that might be indistinguishable from a human in their intellectual capabilities. This is an AI system that might cross the boundaries of specialization and could perform functions in multiple intellectual domains. These systems might even be able to learn from a random set of unstructured data such as what's freely available on the internet.

The Fast Track to Superintelligence

Enter the concept of a superintelligence. For the full explanation of the concept of superintelligence, consider reading Bostrom's previously mentioned book on the topic.

The short version goes something like this: the progress of AI research and development is moving forward so rapidly to the point where nothing is slowing it down. Soon, we will cross a threshold of complexity and capability where AGI is a reality. This could be seen as a point of no return, much like previous scientific discoveries such as nuclear fission, which will change the course of human history. Once AGI is achieved, the exponential pace of advancement will result in what Bostrom calls a Superintelligence, or an artificial entity with general capabilities many orders of magnitude beyond what a human could possess, interpret, or control.

Consider the depictions of AI in science fiction that plays the role of antagonist against humans due to their conflicting judgement of a situation and superior abilities over humans to act on that judgement. HAL from 2001; A Space Odyssey. The Terminators developed by Skynet. The colony ship AI, AUTO from Pixar's Wall-E. A superintelligent system in theory could easily fill the role of any of these characters and prove to be a concrete threat to the human race.

The Need for AI Safety

Elon Musk is one of the more famous personalities that has consistently spoken out about the dangers of unbounded AI research. You only need scroll through some of his tweets on the subject to see that a man who is pushing innovative boundaries daily thinks very strongly about the dangers of AI and superintelligence posing a threat to humanity.

The future of life institute provides extensive details on the subject of AI being a threat to human wellness and even provides a plethora of reference reading to support their points. Some of the main dangers they outline include:

The development of an AI who's interests do not align with those of humanity. Consider the sci-fi trope of a machine that considers humanity a threat to the Earth and decides to wipe it out
The AI is intentionally designed to do something destructive. It's not hard to imagine the conflicts of world politics driving a nation to develop a superintelligent AI with the sole purpose of destroying political enemies.
The AI reaches the point where humans can't reason how or why it does what it does. Do some reading on deep neural networks and you might realize we're already at the point where we really don't know why some algorithms actually work so well.

What Can be Done?

Just as we can turn to fiction to feed our fears about the inevitable threat of AI and the machines taking over, we can also look to it for some answers on how to prevent such a future. Author Isaac Asimov outlined a rather short and elegant set of laws he saw as the fundamental building blocks to ensure robots would never come in conflict with humans. The Three Laws of Robots according to Asimov go as follows:

A robot may not injure a human being or, through inaction, allow a human being to come to harm.

A robot must obey orders given it by human beings except where such orders would conflict with the First Law.

A robot must protect its own existence as long as such protection does not conflict with the First or Second Law.

Besides the potential harm a highly advanced AI might pose to humans, there's also the risk of humanity developing a system it cannot understand or reason about. Even with the sometimes unfathomable complexity of technology we see all around us today, most of it can be completely understood by a human. However, once we trade interpretability for capability, we enter a scenario where our systems are "black boxes" where we can validate the accuracy of its results but cannot reason as to how the result was derived.

So a solution might be that AI systems must be required to explain how they arrived to a solution. While some might see this as a hindrance to progress now, in the future it might be the only way we can feel assured that systems beyond our human capabilities are making decisions in our best interest.

Conclusions

If any of this peaks of interest, I encourage you to do more reading on the subject. Some interesting places to start include:

The TWIML AI podcast episode on the topic
The book Superintelligence by Nick Bostrom
Dr. Michal Kosinski's study on facial recognition and encountering the "black box" problem
The loads of content on the Future of Life website
Elon Musk's twitter feed

Enjoy! 🤖

A Light Introduction to Cloud Services

2019-01-10T00:00:00Z

As software engineers, there are lots of tools available for us to use. We might start simple with a programming language or two. From there, we might explore software libraries that help us be more productive when solving problems, or tools to help with collaboration. If our use-case requires it, we could reach for advanced monitoring tools to alert us when our software is doing something it shouldn't.

At some point in this process, many of us might have crossed paths with the new hotness in software development: The Cloud.

If you're reading this, then you might have at least heard about "cloud technologies". You might want to learn more about what The Cloud is and how it can enable us to build better software.

In short, The Cloud can be seen as just another set of tools for those that want to be more productive when developing software. Most cloud providers offer many of the same types of tools, albeit with slight variations of advertised functionality or developer experience when using them. However, understanding these types of tools and what problems they solve is a key category of information I found very helpful when navigating the cloud technology landscape and implementing my own software solutions.

This will hopefully serve as a high level introduction to the main types of tools available and what problems they can solve. Once you have a handle on them, you should have good context to confidently explore different service offerings by cloud providers.

Compute — Virtual Machines

Virtual machines could be thought of as a foundational service offered in the cloud. In short, you can provision a virtual computer with specified operating system, resources like RAM, CPU and storage, and use it to run whatever software you like. You are charged based on the amount of VM's you provision, as well as the amount of resources they are utilizing. More VM's with more power = more money. You would also most likely have an option to pick where, geographically in the world your VM is deployed. This could help enable faster response times to customers in certain areas or redundancy if a data center experiences downtime.

You can use these services as a platform to host your application for yourself or make it available to the public. They typically don't include any extra features outside of basic autoscaling; so installing, running, and making your app accessible will take some extra time and effort.

Examples of Virtual Machine services:

Object Storage

Storage is another cloud service that is probably pretty easy to wrap your head around. It's a place to store your data that's not on your computer for some money. The complexity comes in the different ways you can structure and access that data, which serves themselves to solving very different problems.

One flavor of cloud storage is file storage, or generically described as "object storage." Object storage is usually a highly configurable place to store data assets based on your development needs. Are you trying to build the backend for a file archive where the data volume is very high but the access rate is very infrequent? Are you handing photo uploads from users at 1000 times per second and photo downloads at ten times that? What kind of transfer protocols are you using to move the data? If these are relevant questions for your software, then object storage services will probably have the configurations and pricing details to solve your data storage and access needs. You are typically charged based on how much data you want to store, how fast you want to access it, where in the world you need it to be accessible, and how much of it is going in and out of the cloud.

Another cool feature of object storage is the ability to host static websites from them. Most object storage solutions offer some type of simple web frontend to serve static assets like a web server (my website is hosted like this!). So if your website doesn't have any interactive elements and can be expressed in plain HTML/JS/CSS, static web hosting through object storage is plenty cheaper than most other application platforms to deploy a website.

Examples of Object Storage services:

Databases

When the data structures you need to persist are a bit more complex than simply storing individual files or objects, but you don't want to have to install and run a database on your hardware or even a VM in the cloud, you might reach for a managed database offering.

Cloud providers have simple and easy ways to get a database up and running with a few clicks. Along with that simplicity, you get a lot of the other strengths of having the service running on a cloud provider's infrastructure like regional availability, built-in monitoring, automatic backups, and automatically expandable capacity. Of course, like most things in the cloud, all these features are fully configurable. But the more you ask for, the more you're probably going to be paying. If the primary business objectives are not managing databases, incurring extra operational cost versus having to hire and manage someone to administer databases is a valid tradeoff.

Most opensource databases like Postgres and MongoDB can be found as a preconfigured, managed services on most cloud platforms with some proprietary offerings available as well. For example, Google Cloud offers the ubiquitous Big Query tool for efficient and affordable storage and access of very large data sets. Similarly, Spanner is Google Cloud's managed, high availability and high performance relational database service. AWS has similar proprietary offerings in the form of Amazon Redshift relational databases and DynamoDB key-value stores.

With managed database services, the main tradeoff for convenience and speed to market is potential vendor lock in to a specific set of tooling and cost depending on the amount of features you require.

Examples of Managed Database Services:

Application Platforms as a Service

When you don't want to worry about systems management of a VM and simply want to deploy your application and manage it at a high level, you might consider a Platform as a Service or PaaS offering.

When working with a PaaS, you can typically get an application written and deployed with only some small configuration in the middle. Assuming you are following the principles of 12 factor application development, getting your app from coded to deployed should only include some small amount of extra configuration. You don't have to worry about VM's or systems administration and can focus more on writing code. You typically pay a premium for this convenience, but for many this is well worth it.

Cloud platforms vary a bit here as far as how approachable they made the developer experience when it comes to directly running apps in the cloud. Some of the first PaaS offerings, like the ever popular Heroku, make deploying as easy as pushing to a git repo and managing your app painless through their web-based tooling. On the flip side, offerings on AWS like Elastic Beanstalk are targeted more at enterprise customers, and therefore trade off convenience for flexibility, customization, and scalability.

Examples of Platforms as a Service:

Serverless Platforms

The paradigm of serverless computing is relatively new in the mainstream discussions of software development. To some degree, the serverless model could be throught of as a direct result of the rise in ubiquitousness of cloud platforms.

The basic idea behind serverless platforms boils down to this: cloud platforms make their money based on the amount of resources their customers use. That could be every CPU or GB of RAM you add to a VM times how long that VM is running. However, the simple fact is sometimes you don't need an application running 24/7 on a VM that's costing you money every minute its up and running. Sometimes you just need something to run a very small percentage of time, maybe to handle a few requests an hour. You could think of it like a shipping company sending out a tractor trailer to ship a few shoes. Why not just send a bike?

Serverless offers an alternative for these unique compute workloads. Instead of deploying a full app, you only deploy a "function" that does the unit of work you want it to and nothing more. The cloud platform then charges you for when the function runs but none of the time it is sitting idle. For example, check out the pricing model for the Cloud Functions offering on Google Cloud Platform. They literally give you the first 2 million times your functions runs FOR FREE. And even after that, its only 40 cents per 20 MILLION INVOCATIONS. (*Disclaimer: These costs are accurate as of writing this)

The clear advantage of this model is obviously the lower cost and opportunity to write less code to get simple jobs done. However a cloud function (today) still takes some time to get "warmed up" and will probably not be as responsive as a continuously running app on the first invocation. Consider this for processes that are pretty simple functionally and don't need to run super fast from the get go.

Examples of Serverless platforms:

Streaming and Data Processing

Similar to my previous article on software testing, it's around here where we get into some of the more specialized tooling offered in the cloud. While specific in their intended use cases, this category of cloud services still spans their own significant portion of most platforms out there and is worth understanding at a high level.

An example of a Dataflow pipeline (https://cloud.google.com/solutions/processing-logs-at-scale-using-dataflow)

Most cloud platforms will offer some kind of scalable, high throughput, data pipeline processing tool. These might be useful when you're trying to build a high volume or throughput system that requires a lot of computing power. A managed data streaming service would give you abstractions around the hardware where your algorithms are running, how to separate and link different steps, and the ways to configure how it scales with incoming data volume. Like other managed service offerings specific to cloud platforms, these data streaming services typically integrate very easily with other managed services like databases and object storage.

Examples of data streaming services:

Another common streaming tool is the Publish-Subscribe or "pubsub" service. These services provide a publish-subscribe messaging system with no worries about infrastructure and minimal configuration and the guarantees of fast delivery of messages. You are charged based on the volume of ingress and egress from the system with the prices typically designed for very high throughput situations. Reach for these if you're building a distributed system, perhaps between multiple, decoupled microservices that need to communicate a decoupled fashion.

Examples of managed pubsub services:

AI and Machine Learning

With the mainstream rise of Machine Learning and AI as an area of software specialization, cloud providers are more than ready to provide managed solutions to some of the main problems posed by this up-and-coming area.

Example of face detection through Google Vision API (https://developers.google.com/vision/)

Most modern cloud providers (especially the ones that already developed high fidelity ML and AI tools for the other business ventures - I'm looking at you Google) offer managed solutions to overcome the barriers to entry into the space. For example, they might provide image recognition tools to provide high quality image recognition without the need to write implementations from scratch or worry about collecting training data sets. They effectively take care of all the implementation and training while letting you, the customer, reap the benefits through a friendly API.

These implementations extend into other areas such as neural networks, natural language processing, with the list growing larger by the day.

As a sidenote, these are excellent tools to grab for a weekend hackathon to take your project to that next level

Examples of managed ML and AI cloud solutions:

Google Dialogflow
Google Vision API
IBM Watson (Yes, Watson from Jeopardy is now a product you can use)
Clarifai
AWS Rekognition

Configuration and Administration

The last and probably most boring but still important to understand items in the cloud toolbelt are the interfaces to manage everything I just talked about, aka administration and configuration tools. To keep the boring section short, I'll break it down into the main components as per my experience:

Identity Access Management: Since projects are often accessed by dozens to thousands of different people, this is a way to keep track of them all are and what permissions they have. Don't give the intern admin access to the production database.
Networking: Just like you can manage all the resources on your cloud platform project, so can you control how they connect to each other through Virtual Private Networks and how the outside world connects to them through Load Balancers and Content Delivery Networks.
Logging: Your software is probably writing a lot of logs that you would like to browse and filter through. Most cloud platforms will have a central way to access and manage those logs for debugging purposes or metrics collection.
Monitoring and Alerting: You might want to know when stuff breaks so you can go fix it before your customer or boss finds out. Cloud providers have options for monitoring mostly everything running on their platform (including the platform itself like Google's Cloud Platform Status page).
Billing: Ah yes, the item at the top of every managers mind (and maybe yours if you are running it for yourself), how much are all these toys going to cost? Considering how this is how these Cloud Providers make their money, they make very well designed and convenient ways to tell you how much of your money they are taking. But hey, for what you're getting, it's not that bad of a deal.

So in (not so) short, that's what The Cloud is all about. If I missed something you think is important (which I probably did), whether a section or link I didn't include, please let me know. And if you're new to this whole cloud platform thing, let me know if this gave you a better idea of what all the hoopla is about.

With that, go and making something awesome.

Getting Started With Open Source

2019-02-26T00:00:00Z

Did you know that a large part of the software you use everyday was probably built with tools and technologies that are freely available for anyone to download, install, study, and modify?

The operating system running the server that's delivering this webpage to you. The library securing your network traffic to this website. The framework used to build this website. All of these thing were build on or with the help of open source technology.

Software being open source means that not only is all of its source code available to download and view publicly, but its also available for anyone to modify and contribute back to. In fact, a lot of the success of open source software by definition is dependent on volunteers contributing changes and collaboratively making the software better.

Contributing to someone else's codebase might seem like a daunting proposition, but all you really need is a computer connected to the internet and a desire to dive into the deep end of an interesting problem you want to contribute your time to.

In this piece, I hope to shed some light on the specifics of how to approach getting started with participating in open source.

Step 1: Go to the Source (Code)

There's no "official" platform or methodology used by the open source community to get their work done. That being said, today most of it is done on Github. There are other git-based alternatives like Gitlab and Bitbucket and even some that are not git-based at all. The Linux Kernel is one of the largest and most active open source projects to date and it is entirely managed through emails of code patches! However, Github is currently the most popular open source platform and is very easy for beginners to get started with.

Github is a place for people to upload their code and have it viewable by the public or privately. Public code repositories or "repos" have many features that make it easy for anyone with some basic knowledge of the software in question to contribute their efforts to making the product better in some way. Not every contribution even needs to be technical in nature. Lots of contributors spend their time moderating dialogs or creating and managing documentation.

A good first step would be to create an account there, if you haven't already, and get familiar with navigating around the site. Check out the trending page for a list of public code repos getting a lot of attention on any given day. Click through some of the different tabs on each repo and explore around. Check out the Issues tab to see what sorts of discussions people are having about the problems they are encountering with the software and how the community has responded in discussion threads. The Pull Requests tab typically has examples of how people have contributed to fixing outstanding issues or added new features.

Most of the remaining steps in this piece will deal with navigating around Github, so make sure you're comfortable with it!

Step 2: Find Something to Contribute To

"Necessity is the mother of invention"

Sometimes the hardest part about getting into open source is finding a project or initiative that you can connect with or are inspired to contribute to. Sometimes you need to go out and find it, and other times it falls right into your lap as a problem you need to overcome. If you work with code and software a decent amount, chances are you ran into some feature you wished was there or a bug you really wish wasn't there.

One example of this comes from an issue my team ran into at work: We had multiple code repos on Github with many team members all making changes and submitting requests to have those changes be reviewed before they were deployed. We needed a way to concisely display all the open changes that needed review for our code repos. After some googling, I found the Github PR Dashboard, which quickly solved our problem. After using it with the team and getting great value from it, we eventually contributed back some features and enhancements for others to use. Check out my past contributions!

If you don't have an existing desire to fix or improve something already, there are some great resources available to get you pointed in the right direction. First Timers Only is a project specifically aimed at highlighting opportunities for beginners to contribute to open source projects. There's a great talk from the React NYC conference on how someone used this kind of resource to contribute code to the React JS codebase which is currently one of the most popular web development tools used today.

Hacktoberfest is another great initiative around getting folks into open source. Every year during the month of October, companies who maintain open source projects encourage new contributors to submit changes for the opportunity to win real-world prizes like T-Shirts and stickers. Any organization is open to participate in this event and each has their own guidelines for how to contribute and win prizes. When October rolls around, be sure to keep an eye out for Hacktober opportunities popping up!

Step 3: Do Your Homework!

Now you have something you want to contribute to, what's next? Well the answer is: it depends. Your open source search might have landed you in a small and simple codebase like some student's side project, or something way more complex and far-reaching like a multi-faceted project backed by hundreds of other contributors and used by multi-billion dollar companies. Both types of repos will have different levels of quality and guidelines on how to contribute.

The best place to start to figure out where to start is the README. Any good open source project should have a good README. Good might mean different things to different people, but you can judge that for yourself. Here are some basic things to look for:

Does it have a concise and informative description of what the project is at a high level and what problem it is trying to solve?
Does it have instructions on how to set up the project on your machine for development?
Does it link to any additional documentation that would be helpful to someone trying to make changes to it?

You can find great examples of READMEs in some of the larger open source projects like React, VSCode, Tensorflow, and more. Use the details in this document to get more familiar with what the repo is all about. Try to follow the getting started steps to clone the code locally and get it up and running.

Next thing to look for is a CONTRIBUTING document. Where the README might include the what and why, the CONTRIBUTING document tells you the how.

Sometimes these details might be included in a README section, so don't worry if you don't find this specific document.

What are the guidelines that the repo maintainers have put forward for how they want you to make changes to the code? Sometimes it's as simple as opening a pull request and having someone approve and merge it. Larger projects might have stricter protocols that include opening an issue, validating the issue is not a duplicate, opening a pull request, having the pull request pass automated test suites or CI process, and finally being approved by a maintainer. Different projects operate in different ways, so be sure to know how the one you want to contribute to does.

The VSCode project has a great CONTRIBUTING document that I've always been directed to as a reference.

Last but certainly not least is the CODE OF CONDUCT document. This document provides the guidelines by which contributors are expected to conduct themselves when collaborating online with the community. Some can be short and sweet and simple say "Don't be a jerk." Others can get into more details about what kind of interactions and behavior are considered inappropriate.

The Angular project has a short and sweet code of conduct that get's right to the point very effectively.

Step 4: Fork and Code

Disclaimer: These next two sections assume you know the basics of Git including common operations like how to clone, branch, commit, merge, and push.

Now you've found some code you want to contribute to and you're familiar with the process put in place by the maintainers to do so. Next we're going to get into the nitty-gritty details about how to make your changes and actually submit them.

Github has a feature called "forking" that essentially means: take this repo owned by someone else and create a linked copy in my personal Github profile.

This allows you to create a branch and push code to your forked copy without having write access to the main repo.

So now you should do exactly that. Clone the forked repo to your machine, make whatever changes you planned, and commit to a branch on your forked repo. If applicable, follow any branching, code style, and testing requirements outlined in the contributing guidelines.

Step 5: Open a Pull Request

Once you're happy with the changes, you can open a Pull Request.

Make sure that the base branch you are proposing to merge your branch into is the appropriate branch of the original repo. That way the maintainers will see your open PR in their list of pull requests.

Again, follow the contributing guidelines to decide which is the correct default branch the maintainers want you to merge into and what details are expected in the Pull Request description. Some repos on Github are set up with Pull Request templates that will pre-fill the description with a basic scaffold you can add details too.

Now just wait to get some feedback from the code owners to see if they think your changes are ready to be merged. Sometimes its a quick thumbs up and other times there might be some back and forth where additional changes might be requested. Remember that this whole process is about teamwork and communication. You the contributor and the maintainer are on the same team, so be sure to respect the code of conduct for contributing and don't get discouraged if you don't get it right the first time!

Once that's done, you did it! You have officially contributed to open source!

I hope this guide provided some insight into how to get your foot in the door to contributing to open source. I'd love to hear your feedback in the comments or on X.

I've since written a follow up to this piece about how to open source your own projects, so be sure to check that out next.

If you're looking for some other great resources:

I'm going to plug the great talk I mentioned above again because it has some great examples of PR's being rejected how it was dealt with properly
First Timers Only: A resource dedicated to those contributing to Open Source for the first time
The ReactJS Contributing docs have guidelines specifically for directing beginners to appropriate Issues to contribute changes to
Kent C Dodds has a great video on the topic of contributing to open source for beginners

How to Open Source Your Code

2019-04-01T00:00:00Z

In my last post, I outlined what open source is and presented some steps for how to get involved. Every open source project available today, even those with many thousands of contributors, all started with at least one person who had the drive to make what they were creating available for other to freely use and contribute to.

If you fall into this category of people but don't have a good idea of how to get started, then this is hopefully a good place for you to start. We will cover some of the high level concepts and steps you can take to get your project ready for the world of open source.

While these are my top picks for how to properly prepare a project to be open sourced, this list is by no means exhaustive. The best source for open source is always the community at large. Everything said here is based on my experience participating in open source as well as learning from others maintaining their own projects. After reading, I encourage you to go find one of the many amazing open source projects out there and follow their examples. There are some links at the end to help you get started!

Step 0: Identify the Opportunity

This is more of an optional step but, in my opinion, since open source is all about adding value through collaboration, your first step might be to consider some things about your code.

Is this something that you got value out of?
Is this something that you think others would get value out of?
Do you think more people contributing would improve the quality of what is being provided by the code?

Big disclaimer: these are not questions that necessarily need a "yes" answer to move forward. The answers will mean more or less to your situation. Whether you're open sourcing your code to get a lot of contributors involved quickly, or just as an exercise to become more proficient in the relevant skills. Just consider how the answers might affect your results.

Step 1: Prep the Code

The baseline requirement for a project to be viable in the open source landscape comes down to the thing that makes open source a concept in the first place: enabling other people to be productive using, modifying, and improving its code. With that obvious requirement, you need to ask yourself a simple question:

If I handed someone this project right now, how hard would it be for them to read the code, run the code, and change the code?

You could follow up on that with:

Are there any tools that the contributor should install or be familiar with before getting started?
Does it matter what platform the person is working on (Windows vs Mac vs Linux)?
How can the person be confident that making a change in one place won't break something else in the code, i.e are there any tests?
Is the code well organized and easy to follow?

All of these points are really to say that if you're going to be putting something out there with the intention of others picking it up and working on it, you should take the necessary steps to set them up with a quality product. There are many books out there that outline some of the best practices for writing good code (Clean Code comes to mind). You might consider handing off your project to someone with technical knowledge but who's not familiar with it and get their feedback for how easy some basic development task was to complete.

Step 2: README

The README might be the most important document included with a project when it comes to providing a newcomer with the summary of what your project is all about. In addition to a brief summary of what the the code is trying to accomplish, the README is the first place you can answer some of the questions listed above. Someone stumbling on your code should be able to start by going through the README and end by at least being able to understand what the code can do, download it to their machine, and run it.

Try to find some examples of cool README documents from some of the prominent open source projects on Github. As flashy as they are with badges and logos, remember that they all answer the basic questions listed above in some way.

Step 3: The License

The open source license is probably the second most important document you want to include in your project before releasing it out into the wild. In short, since you're putting your code out there for anyone to see, you probably want to have some control over what people can and can't do with it once they have it. For example:

Are you OK with someone using it to run their business?
Are you OK with someone modifying it and selling it as their own, new product?
Does the entity using your code need to explicitly give your credit when using any original or modified version of your code?

The good news is, so much of the heavy legal work has already been done by other smart folks on the internet. Github does an amazing job with their helpful documentation as well as reminders when you create a public repo without a license to make sure you include the right one for your needs.

Step 4: How to Contribute

A set of contributing guidelines is the next important piece of documentation you should include, usually in the form of a CONTRIBUTING document much like the README. The CONTRIBUTING document or set of documents serve to inform the prospective newcomer to your code on how you as a maintainer want them to go about making contributions.

A CONTRIBUTING doc serves to answers some questions like:

What are some ways I can contribute in the first place? Are you, the maintainer, just looking for bug fixes or new features?
What's the first thing I should so when I want to make a change to this code?
Should I create an issue or just fork and pull request?
Are there any branching conventions I should follow?
Should I write my commit messages in a certain way?
Who are the maintainers aka. who's in charge here?
Do you follow any coding styleguides?

Here's an example of a basic CONTRIBUTING document I came up with:

Hello! Thanks for contributing to <Insert Awesome Project Here>

# How to Contribute
Step 1. Please open an Issue with a description of what you're trying to add/fix/change

Step 2. Fork and create a feature branch in the format <some-description>/<your issue number>

Step 3. Please squash all your commits into one with a good commit message before opening a pull request

Step 4. Open a pull request, reference your original issue, and provide a concise description of how your changes fixed the issue

Step 5. Your PR requires 2 approvals from maintainers before it can be merged.

You can go as wild as you want with it. Just like the code, all the documentation is also open source, so it can also evolve and improve along with your project! Check out Github's documentation for some amazing examples of contributing documents in the wild. I particularly like the short and sweet Open Government Contributing guidelines document.

Step 5: Community

Open source is at its best when you have a strong community behind it. Whether is just you and a couple of maintainers, or a project that you foresee spanning hundreds of contributors, it's important to set a precedent for the spirit of collaboration you want to establish around your projects.

While documentation like the README and CONTRIBUTING guidelines could also touch on this subject in some ways, the CODE OF CONDUCT is where you should be most direct about how you expect people to behave and interact with each other.

People might not be explicitly asking the questions that the code of conduct document seeks to answer, but it can always be there to set a baseline standard of conduct if issues were to ever arise. Some of these implicit questions might be:

Are contributors expected to converse with each other as if they were in a professional setting like an office, or is the tone more informal?
What are some of the core values someone should adhere to when approaching interpersonal interactions within the community?
What should someone do if they notice someone behaving inappropriately within the community?
What, if any action, would be taken if someone were to break the etiquette rules?

Here's an example of the simplest code of conduct document I thought up.

Code of Conduct

- Be kind
- Be welcoming
- Don't be a jerk

Feel free to copy if you find it helpful!

But in all seriousness, there are lots of great examples available to reference just like all the other documents. One example is Facebook's Open Source Code of Conduct which they link to in all of their open source project repos.

Step 6: Consistency

Making sure your open source project is successful and productive depends, just like any other project, on you giving it the appropriate amount of time it needs to succeed. This could include simple actions like regularly updating dependencies on major releases, or going through all the open Issues and Pull Requests at least once a week. It's always better to have someone come across your repo and see commits and merged PR's that are a few days old rather than a few weeks or months old.

For larger projects with many users and contributors, it might mean making sure you're being responsive to emails or messages. A common practice among larger open source projects is to have a public instant messaging platform like Slack available for anyone with questions or suggestions to join the community discussion about the project.

Moving to GatsbyJS

2019-05-21T00:00:00Z

There are lots of tools to build websites freely available to download and use online. You might want to go at it with just plain HTML, CSS, and some JavaScript. This is how I built my first personal website and unless you're trying to get fancy with frontend features or content, this might have worked well for you.

Overtime, I got the itch to move my website development to something a little more robust in terms of tooling. Not so much because the content there was complex enough to merit a full-fledged frontend framework, but more so I could have a place to practice my web development skills with some modern frameworks, tools, and abstractions. The web development landscape moves so fast, I wanted to make sure I had my own sandbox to experiment and learn easily.

Static Site Generators

Since my site was basically just a static web page with some CSS and JS for responsiveness and styling, I didn't feel like I should reach for a full-featured framework like Angular or Ember. I wanted my site to be driven by simple content while I would host more specific content like videos and long-form publications on managed platforms like YouTube and Medium.

I found that static site generators fit my use-case perfectly. In short, I would be able to take advantage of the modern features of a frontend framework during development and publish plain HTML, CSS, and JS to serve to clients. Since I didn't expect to have any dynamic content on my site, there would be no restriction on what I could build. Moreover, hosting a static site is a lot simpler, as platforms like Github Pages provide easy ways to serve static content for free.

NuxtJS : Moving Beyond HTML/CSS/JS

While React was already dominating the web development landscape by this time, I was dabbling more in one of its mainstream competitors: VueJS. I have more or less come around to liking and even preferring React today, but back then I was initially attracted to Vue by its similarities to AngularJS. I had a lot of experience with Angular at that point and I wasn't quite ready to make the jump to the new hotness that was React.

While researching some popular static site generation tools, I came across NextJS. It is developed and maintained by the Zeit team and provided a full featured static site generation solution. Just what I was looking for. The one tiny issue was that it leveraged React.

After some more stubborn digging, I came across NuxtJS, which unashamedly advertised itself as NextJS with a fronted by Vue instead of React. I happily picked it up and was on my way to modern web development land.

Once I was happy with an initial version, I generated my static assets and pushed it up to my Github repo. Like I mentioned before, Github has excellent support for hosting static sites. Their documentation about Github pages, tight integration with repos, and the gh-pages tool makes it effortless to develop and host static sites.

Website V2 DONE. As I expected, it was a LOT nicer to build having modern tools and features like hot-reloading and bundling available to me. I had the modern web sandbox I was looking for.

GatsbyJS : The New and Shiny

I first heard about GatsbyJS on the SyntaxFM podcast (which is great by the way, go subscribe). It was discussed in comparison to NextJS which I was already familiar with from my previous research. There were a lot of good things I heard about Gatsby, but nothing that had me wanting to switch my site over. Sure, it was a static site generator with modern web development tooling and features, but that's what I already had with Nuxt!

Fast forward a few weeks and I'm hearing some more buzz about Gatsby around the web and among other devs. There was a full-day Gatsby workshop for beginners happening at my workplace that I was interested in signing up. Normally I preferred diving into new frameworks on my own time, but I figured this was an easy jumpstart to something that was clearly picking up steam in the community. There had to be something there I was missing out on, right? After getting a quick intro to the framework, we did some hands on development with Gatsby, and that's when I finally saw what all the hype was about.

Plugins

What really made Gatsby stand out to me in terms of developer experience was the plugin system. At its core, you can build a complete Gatsby static site with plain-old React and CSS styles. To add to this, plugins are easy, plug and play node_modules you can import during development to make building your site far more efficient and manageable.

Like I said before, the site I built was really quite simple, nothing more than a landing page with links to external sites with my other content. However, Gatsby plugins sparked some cool ideas for enhancements to what I already had. For example, instead of just providing a link to my profile on Medium, I could drop in the gatsby-source-medium plugin with some minimal configuration and I could now have my site automatically display previews of my latest published content.

Similarly, I never thought about how I didn't integrate Google Analytics into my site to track user traffic. While integrating Analytics is already easy enough, it doesn't get easier than npm installing gatsby-plugin-google-analytics and dropping a tracking id into your Gatsby config. The framework takes care of the rest during site generation.

Finally, the user experience of browsing through their plugin repository is top notch. Every one links to an info page with easy access to the relevant Github repos in case you need to dive some code or submit an issue.

Progressive Web App Features

Progressive Web Apps or PWA's are a class of web applications that adhere to certain standards or performance and accessibility. In general, if you build your websites to the PWA standards, you will make it easier for everyone to use your website, regardless of their network or hardware capabilities.

Faster load times and more responsive behavior are the main claims to fame in my opinion. Dan Abramov from the React team called this out about the ReactJS site and its freaky fast performance.

Conversion: The Developer Experience

Although Vue and React have pretty different paradigms in terms of how they expect applications to be structured, the simplicity of my website allowed me to basically just copy paste over what I had. I started with a barebones gatsby-starter-hello-world and started moving things over. The biggest manual work I had to do was convert my HTML markup into JSX, which was a step forward since it helped me modularize the markup quite a bit.

Routing between pages is handled implicitly. If you drop a home.jsx file into your src/pages directory, Gatsby will build it into the /home route automatically. CSS and other static assets like images and build in automatically from the static directory, and Gatsby does a great job bundling and minifying everything behind the scenes for efficient delivery to the client. I only had one page to worry about, and this model was just like Nuxt, so there was no major things to learn here.

Switching my site over to Gatsby basically out of the box provided me with a pretty significant boost in web performance as measured by Google's Lighthouse analyzer. I tweeted my experience as such.

More and more

Some things I'm still exploring but know are pretty unique to Gatsby include:

GraphQL support: Basically anything data-related in your application can be accessed through a full GraphQL server running in your development environment. The Medium plugin I mentioned earlier is driven off this.
CMS Integration: I'd like to eventually move my site to a BYOF or Bring Your Own Frontend system where a managed platform could host and serve all my data and API needs while my Gatsby site could continue to run statically. Netlify and Drupal and a couple of these on my radar.

Suffice it to say, I have no regrets converting to Gatsby. I'm pretty convinced the hype was real. Gatsby is here to stay as a remarkably solid choice for modern static and progressive web app construction.

I'm looking forward to improving my site with the suite of tools and plugins offered by Gatsby and well as the fresh developer experience of working with it as my static site framework.

If you have any thoughts or suggestions, please let me know on X. Also keep an eye on my website for upcoming additions!

Why I Think Software Should be Rewritten Every Three Years

2019-06-11T00:00:00Z

One of the most common tropes of working as a software engineer I've noticed is the constant lambasting of old code. Anything older than a few years was never described by my peers as anything close to elegant, easy to read, maintainable, or generally pleasurable to work with.

There are many existing posts out there (at least one I've read) that outline how to emotionally deal with the inevitable headaches of old code. It came off as something to be coped with, not something that could be solved.

This got me thinking about a few things:

Is the reduction of maintainability of a codebase over time inevitable?
What causes this kind of code to rot in the real world?
How do we fight it?

Codebase Maintainability Over Time

I recently read a post by Martin Fowler where writes about the tradeoff between the cost to produce and resulting quality of software being developed. He refers to a phenomenon where, over time, a codebase gets populated with increasing levels of cruft, which he defined as: "the difference between the current code and how it would ideally be." When you dive into a codebase, you probably want as little as possible getting in your way of understanding what that code is doing. Cruft is what you're seeing when you open up that 2000 line file, written by 10 people you've never met, over a period of 5 years.

Fowler argues that it's in the best interest of the engineers as well as business partners that code quality and minimization of cruft be at the forefront of thought when making changes to software. He states that taking the extra time to write quality code in the present has compound benefits for the future. Internal quality means it's easier to modify software, which means faster delivery of features.

Your users don't care about software quality, they only care about the velocity of new features being delivered and their quality. Taking extra time now to deliver a feature with quality code now only helps deliver the next feature in less time. Conversely, taking less time to deliver a feature faster with less quality only hurts your ability to deliver the next feature faster due to the addition of more cruft.

Yet the point he was making was somewhat softened when he noted:

…even the finest teams will inevitably create some cruft as they work.

So maybe it's fair to say software quality is doomed to decline over time? Perhaps that decline might be slower or faster depending on the level of effort put into minimizing it. But it will happen.

Code Isn't the Only Thing That's Changing

When we think about the reasons why changing software becomes harder over time, we might only consider the increasing number of lines of code or bad code practices slowly creeping their way in. But there is a lot more changing, not only in the code, but all around it. This only adds to the struggles holding teams back from keeping the software running and maintained.

Business requirements

It's the common trope you might be familiar with: "The requirements have changed…again!" As much as we'd like to think we can either properly spec a piece of software's requirements ahead of time, or work with "agile" methods to keep your requirements at pace with changing feedback and expectations, ultimately the needs your software serves typically changes more with each passing iteration of development.

I'm no structural engineer or architect, but I consider the reasons why builders or city planners would decide to demolish and rebuild a building rather than continuously enhance it. Obviously, physical materials will degrade overtime unlike code. But what if the requirements of a building changed like the requirements of software? Suddenly the location of the structure could change between weeks, like the deployment environment of software. The patrons of the building could start to expect different things from it, like the changing expectations of software users. Where the building was designed to withstand blizzards, suddenly earthquakes are what's happening day to day. At what point do we say it's time to demolish and start over?

This is probably a massive generalization when discussing software depending on the type of business or industry your software is serving. However, I still feel it valuable to acknowledge the correlation of how quickly your requirements change to how fundamentally irrelevant your codebase becomes over time.

Software dependencies

Most software is built with other software that's just as prone to change as anything else we're discussing here. Libraries, frameworks, design paradigms, and certainly entire programming languages come and go with the rapid pace of the software engineering landscape. The longer that a single piece of software stays stagnant in this landscape, the more likely it is to become fundamentally detached with it.

This could mean that your software harbors critical security vulnerabilities patched in more modern iterations of its included frameworks or libraries (Apache Struts comes to mind). The developer experience might suffer from working with these dependencies due to waning support for tools. Solving the software problem becomes an issue of keeping the solution in bounds with the dependencies and tools at hand rather than considering all the possibilities for solving the problem most effectively and efficiently.

Team members and maintainers

It's increasingly common to see folks in the software engineering world to not stick around the same job for more than a couple of years. Employers are increasingly acknowledging the value of technical problem solvers with a wide breadth of experience and even encourage them to be flexible in their career paths with respect to their place of employment. This is clearly a positive for the individual, who has the increased agency to jump between companies and teams and contribute their widening breadth of knowledge to solving hard problems.

What this trend results in is teams with increased turnover, meaning more pains to get people up to speed with existing systems. Conversely, this also leads to teams staffed with problem solvers that can pull from their previous experience and look at solving problems from diverse lenses. Why not allow these fresh minds to lay the foundation differently with a fresh set of eyes? We should not discount the clear win of having a fluid set of minds working the problem just because something that "works" is already in production.

What happens when the codebase you're working with was started and worked on by people you have never met? What about when every person on the team inherited the code and had no say in its initial creation? This to me is another inevitable and difficult inflection point where teams need to take a hard look at why they shouldn't have the freedom to just start over.

A Clean Start

Given all of my previous points, here's what I'm proposing: Software, given enough time, will reach an inflection point where the cost to maintain the existing solution far exceeds the cost to rewrite it. Here are some potential reasons why:

Business requirements the software was originally built for have moved far enough away from the original requirements.
The external dependencies of the software have changed beyond the point of simply upgrading or retrofitting.
The people working on the software had no skin in the game when it was originally being created.
The design or architecture does not directly cater to the current problem being solved.

If you see any one of these factors becoming increasingly apparent over time, you need to make a decision as to when it's appropriate to start over.

I picked the three year timeframe in the title of this piece as a rule-of-thumb based on my experience. It's around this point where someone working on a project of this age starts to encounter friction in one of the above categories. This could vary wildly between problem domains, but that's the number I thought was right for what I know.

Reaching a Steady State

After considering this you might say, "if you're rewriting everything every three years, then at some point you going to be doing nothing but rewriting stuff!"

Certainly, the tradeoff between doing a rewrite and just continuing to change the existing codebase will cross at some point. As you see the variables around your software declining, like new feature requests, so should you see the need for a rewrite of the software becoming less necessary.

As another general rule-of-thumb: Stop rewriting when external variability has declined to the point where the following are more or less at a steady state between periods where a rewrite is considered. Some factors to consider after a three year time period might include:

The same people/team are still working on the software.
No new requirements are coming in that fit the profile of the existing software. If the requirements are different enough, you're probably going to write something new anyway.
Any refactor or update to software libraries or frameworks provide no additional internal value to the developers or external value to the users or business.
Rewriting your software it is direct conflict with the best interest of your users (I can't see anyone clambering for a full rewrite of airplane autopilot or nuclear reactor control system software every year).

I'm sure these are plenty of projects that are totally outside the realm of ever needing a complete rewrite. But be careful not to lump them in with other projects that don't meet these criteria simply because they "work in production now."

Conclusions

"Change is the only constant in life"

-Heraclitus

Just as time inevitably passes, so do the factors around what ultimately made your software what it is. Requirements, tools, and people are in constant flux over time which inevitably leads to cruft in not only lines of code, but also in the relationships between your software, its users, and its maintainers.

I want us to critically question the apparent inevitability of legacy code being a negative experience. Once we come to terms with the cause of this problem, I want us to confidently say we know how to combat it. We should not be afraid to start with a clean slate more often than staying safe in the status quo.

This is my first crack at an opinion piece, so I'd love to hear any feedback including counterarguments or supporting experiences. Everything said here was my own opinion and not reflective of any person or entity I've worked with. Please bring your own thoughts to this discussion here or on X @Nirespire.

Automating Dependency Upgrades with Dependabot and CI

2020-01-08T00:00:00Z

I'm a big proponent of keeping software up to date. Especially in the modern day where it feels like new critical security vulnerabilities are popping up in software every other week.

There's a whole industry, multiple academic fields, and career tracks just focused on this topic of software security. Smart people are always finding ways to make it easier for devs to implement best security practices when writing code.

One of these many best practices is always keeping your dependencies up to date and actively upgrading them when known vulnerabilities are published. In the past, this was a mostly manual process. If a new security vulnerability was published, like a CVE, software maintainers would have to:

Be aware the CVE was published
See if it was related to any code they owned
Find the places where it applied
Upgrade where necessary
Make sure the software still works correctly

Let me show you how the above steps have been made easier for us with a tool recently acquired by Github called Dependabot and the principles of Continuous Integration.

Dependabot and Github

Dependabot is a product developed to provide automated dependency upgrades to software repositories. It was originally a paid product that was acquired and integrated into Github.com in May of 2019. Since then, every public repo has had access to Dependabot's integrated features out of the box when creating repos on Github.

The Github Security Tab

The Security tab is the main way that Dependabot and other automated security features on the Github platform are brought to users in their code repos. These features include automated reports of new security vulnerabilities in the repo's dependencies.

If you have your code hosted on Github in a repo that you have contribution rights to, head over to the Security tab and select the option to receive Automated Security Updates.

Note that this feature has some restrictions as to which types of repos it is enabled for and which programming languages / package managers it supports. Most of the projects I work in are public repos that include NPM and Docker as package managers, which are both compatible.

Below is an example of what an alert looks like once Dependabot receives a new CVE publication and identifies that it applies to your repo.

Once you have this set up, you can even set up your notifications preferences to have Github email you when a vulnerability is detected on one of your repos or provide a weekly report of findings.

As far as checking the boxes we mentioned above, for every supported repo you configure this for, here's what we've now got covered:

Be aware the CVE was published ✅
See if it was related to any code they owned ✅
Find the places where it applied ✅
Upgrade where necessary
Make sure the software still works correctly

Automated Dependency Upgrades

When you click on the Security Alert, you get information about the relevant CVE publication as well as an option to have Dependabot automatically generate a Pull Request with the appropriate dependency upgrade.

This option will not always be there and you might have to make the fix manually yourself, but consider yourself being 90% of the way there by knowing the vulnerability is there and being handed the steps to fix it.

That's another item done on our checklist:

Be aware the CVE was published ☑️
See if it was related to any code they owned ☑️
Find the places where it applied ☑️
Upgrade where necessary ✅
Make sure the software still works correctly

Custom Configurations

Dependabot is highly configurable if you would like finer control over how it behaves. You can set things like what package management systems to cover, how frequently it should scan your repo, and even assign specific users to address any security issues with dependencies that are identified.

Below is an example .dependabot/config.yaml file I included in the repo for my personal website.

Automated Testing and Continuous Integration

The last item on our automated dependency upgrade checklist is a way to make sure that upgrading our dependencies doesn't break our software. There's always some inherent risk with making upgrades since changing code could imply an unexpected change in functionality. However, this risk is well worth it compared to leaving security vulnerabilities in your dependencies. Moreover, this risk can be mitigated with a few extra best practices and automation steps.

Firstly, if your software and codebase is complex enough, you should always include automated testing. If you're interested in what to include, check out my article on the different kinds of software testing. If you've written good tests, then a passing test suite should be enough to say the dependency upgrade didn't break anything.

Furthermore, you can adopt some principles of Continuous Integration (which I also describe in more detail in another article) and have your tests run automatically when a Pull Request is opened. That way, when Dependabot automatically opens a PR or you do it manually, your CI can run your test suite and the PR is only merged when it passes.

Github Actions is a way to implement CI, also directly integrated into Github. There's a hole slew of ways you could implement running tests through Actions or even another CI tool, but here's a suggest list of high-level steps to implement in your CI pipeline:

Trigger your CI when a PR is opened on your repo
Run tests on branch the PR is for
Publish the results of the tests to the PR on Github
(Optional) Configure branch protection rules to block merging the PR until the CI check has passed

If your codebase or app is just not that complex and manually testing it suffices, the above steps might not even be necessary when making dependency upgrades. For example, my personal website is just a single page static site with basically zero complex functionality. If it builds and renders, I consider my testing complete.

With the above steps in place, we have now checked off our last item:

Be aware the CVE was published ☑️
See if it was related to any code they owned ☑️
Find the places where it applied ☑️
Upgrade where necessary ☑️
Make sure the software still works correctly ✅

Keeping your software dependencies is easier now than I think it has ever been. I believe it is every developer's responsibility to be aware of best-practices and take advantage of the constantly improving tools we have freely available at our disposal.

If you have any thoughts about this topic, please leave a comment or reach out on X @Nirespire.

Tracing and Observability

2020-02-25T00:00:00Z

Think back to the last time you checked the tracking information for a package you were expecting to receive. You might have followed a link in your email that gave you a breakdown of where and when your package was received and shipped out of various locations. You could make a mental map of what shipping facilities passed through around the world it and how long it spent there and on the road. From that information, you probably got a sense of what kind of journey your package took and why it took as long as it did to get to your doorstep.

We can take this principle of tracking the path of a package across various stops and apply it to the flow of information between software systems. In the current paradigm of distributed microservices, where a simple request to load a webpage might bounce between a dozen different applications, it becomes valuable to observe or trace the path of data requests across applications and networks.

Client-Server Example

I like to bring the concept of open tracing down to the level of two applications in a client-server model. We can take the concepts here and expand on them to apply to any number of applications orchestrated together.

Say, for example, we have a simple web server application that receives a request at the endpoint /hello and sends back a static string of text "hello" back to the client.

From the perspective of the client, they send a request, wait some time for things like the network between itself and the server as well as time for the server to process the request. Within the server, there is only a single action that occurs, within the context of the same application. We can visualize this entire transaction in a "span". This span has a begin and ending time as well as some detail or "tag" about the type of operation being performed.

Now the client knows about the request and response, including what was sent, when it was sent, what was received back, and when it was received back. The server knows something similar but from its own perspective of when a request was received and responded to.

The missing piece here is that without us drawing out the scenario or manually associating these events between the two applications, there's no easy way to link them together and gain insights about this interaction.

Tracing Requests

In order to start creating a complete picture of the interaction between these two applications, we need an outside "observer" to gather information about the client and server interactions. That observer can then look at the interactions holistically and gain better insights by looking at the complete picture.

In this example, let's say that the client and server know about this observer and report every time they send or receive data. They will tell the observer about every relevant event in the exchange with the following information:

Who they are
Who they're interacting with
If they're sending or receiving data
What data they're sending or receiving
A timestamp when that event occurred

The interaction might follow as illustrated below:

Here's the breakdown of actions that the Observer is recording:

Client sends a /hello request to Server at time0

Server receives /hello request from Client at time1

Server processes request and responds to Client with "hello" at time2

Client receives "hello" from Server at time3

The observer is now able to correspond to the events of this two-party interaction as a contiguous group of information. Here are now some interesting insights we can gain from this simple integration between just two systems:

Where was the most latency happening? Maybe it was in the network between the client and server, or maybe the server processing time.
If the request failed, did it ever make it to the server or was it lost in the link between it and the client?

We can even take it a step further and break the processing in the Server into multiple steps and report those to the Observer as well.

Client sends a /hello request to Server at time0

Server receives /hello request from Client at time1
2.a. Server parses the request from the Client at time1a
2.b. Server runs the buildResponse() function to provide the appropriate response to the requester at time1b

Server responds to Client with "hello" at time2

Client receives "hello" from Server at time3

Now we can go even deeper and see how long certain processes are taking on the server or even exactly which process might have failed during an exchange.

Spans and Traces

Let's take the above example of information that the Observer is recording and add two more pieces of information:

A Span ID that an application generates every time it reports an event
A Trace ID that each application will pass along if the data it receives contains it. If not available, a new one will be generated and reported.

If the applications attach this metadata to the events they're sending to the Observer, now the data the Observer records will look something like this:

Client sends a /hello request to Server at time0 (TraceID: hellorequest1, SpanID: 1)

Server receives /hello request from Client at time1 (TraceID: hellorequest1, SpanID: 2)
2.a. Server parses the request from the Client at time1a (TraceID: hellorequest1, SpanID: 3)
2.b. Server runs the buildResponse() function to provide the appropriate response to the requester at time1b (TraceID: hellorequest1, SpanID: 4)

Server responds to Client with "hello" at time2 (TraceID: hellorequest1, SpanID: 5)

Client receives "hello" from Server at time3 (TraceID: hellorequest1, SpanID: 6)

The Observer can now use the Trace ID to group these series of events together and break it down into its individual parts using the Span IDs.

Since this will probably clutter up the component diagram, this information can be summarized as a series of spans in time. Note the functions on the client to process the response are omitted, but you can surmise what the spans for those might look like:

The Span ID "hellorequest1" covers all the spans below it and logically groups the tracing information of the events happening within it like the client sending the request, the server receiving it, and the server processing to send the response back to the client.

The Client generates a Trace ID when it initiates the interaction. From then on, each participant in the exchange knows to pass on the Trace ID if it is present. Each participant also know to generate a new Span ID every time data is moved from one logical context or operation to the next. Every event is reported to the Observer along with these IDs. In that way, each complete transaction can be logically grouped but also deconstructed into its individual pieces once assembled at the Observer.

Tracing Multiple Applications

Let's take our example with two applications and extend it to four applications.

Let's say the exchange still starts with our Client application, but this time it's sending a /readinfo request to the Server. The Server can't process this request by itself, so it sends a request each to two other applications, let's call them the SecurityService and InfoService. When Server receives a /readinfo request, it has to first ask the SecurityService if the requester has the right permissions to read this info. If that is successful, it then calls the InfoService to pull the info, and finally sends it back to the requester.

Let's draw this interaction out. We can label the order in which the operations happen and we can then infer the series of events being recorded by the Observer.

Here's what the Observer recorded based on the events each application sent it. All the events are listed with the numbers from the diagram matching the numbers on the list. I'm omitting timestamps and ID's to save some space, but you can fill in the blanks:

Client sends a /readinfo request to Server

Server receives a /readinfo request

Server sends an /access request to SecurityService

SecurityService receives an /access request

SecurityService responds to the /access request

Server receives the /access response from SecurityService

Server sends an /info request to InfoService

InfoService receives an /info request

InfoService responds to the /info request

Server receives the /info response from InfoService

Server responds to the /readinfo request from Client

Client receives the /readinfo response

Just by adding two players into the mix, the number of events being recorded has grown quite a bit. We can visualize the same list of events as spans to provide a better view of the execution path of the /readinfo request:

Notice all the events are still grouped in the same TraceID, but we can see the span of each individual service passing the request between each other and working together to process the final result to the Client.

We could extend the granularity of the spans further by including details about functions and subroutines running within each application.

Out of the Example and Into the Real World

The above concepts are simplified versions of terms and constructs formalized in the Opentracing Specification for microservices and distributed applications.

There are many opensource libraries and software that implement the Opentracing specification. You can integrate these into your own applications to gain powerful insights into the interactions of your microservices.

Once your application can communicate via Opentracing, you still need an Observer to record all the events being emitted from the applications. There are many systems that implementing the Opentracing spec. Zipkin is one of these popular distributed tracing systems that you can install and run yourself. It plays the part of the Observer from our examples and consumes tracing data from applications that adhere to the Opentracing standard to provide interactive visuals of your application traces.

If you're like more information about Opentracing, you can check out their website which has specification docs as well as guides to get started with Opentracing.

You can also play around with zipkin which has library support for pretty much any programming language you're probably thinking of using.

Let me know your thoughts about this article or Opentracing in general over on X.

Don't (always) use a Database

2020-12-28T00:00:00Z

I was recently having a design conversation with some engineers on my product team. We were discussing the implementation of a feature that dealt with saving user settings on a web app. When thinking about the concept of persistent storage, my brain automatically tended to go straight to the obvious tool that provided programmatic persistent storage: a database.

Databases generally provide a flexible paradigm for storing different formats of data and standard APIs to read and write that data programmatically.

However, the more we discussed and the more I thought about it, this was a case where storage locally on the browser was more than enough. We didn't care if the user could access their settings from multiple sessions or devices. It was just a few toggles that would typically be used within the same browser and specific to a single user. Why bother having to setup and maintain a database, adding complexity to the architecture and more cost of ownership?

So problem solved, right? Well, yes, but the next question I asked myself after the fact was: what other places had I been defaulting to using a database where it really wasn't the best option?

"Best" is very subjective and could mean a lot of things. My main consideration here is how cost effective (from a time and money perspective) is it to implement your desired feature using the given storage solution?

Here are the two basic criteria I could infer when asking myself, could this service provide the same functionality as a database?

There is a freely available method to store and retrieve some amount of data to and from the service
There is a public API that can perform those functions

The following is my basic list of services that don't present themselves as databases, but with a little imagination, can totally be used as a database.

Disclaimer: none of the below options are going to scale anywhere beyond demos or personal projects. Temper your expectations when you're basically repurposing the free-tier of popular online services for your custom storage usecase.

Google Sheets

If you have spent any amount of time browsing the Show section on Hacker news, you've probably seen many versions of this one: using Google Sheets as your database backend. In case you didn't know, Google Sheets is Google's online spreadsheet tool you can use to author, share, and distribute Excel-like spreadsheets for various purposes. Whatever storage space your sheets take up gets added into your Google online storage total (which is an aggregation of various google storage services like Gmail, Drive, Photos, etc), of which you get a chuck of storage totally for free (15GB as of me writing this).

Combine that with the available Sheets API, and you can basically have yourself a free database backend. Rows on a spreadsheet basically equate to rows in your database.

Imgur

Storing media assets like images can be a resource-intensive task. You could get fancy and try to encode and compress your images into a traditional database, however many of the disadvantages of having to process raw bytes of data might outweigh the benefits.

Imgur is a massive image hosting service that also provides a simple developer API to upload and retrieve images. There is a rate limit (50 images per hour as of me writing this) so don't expect this to scale up to real production workloads. But this, combined with a way to keep track of the IDs of your uploaded images, just might get you through your requirement.

Github

Now this one was interesting because it was a project I found that leveraged the "backend storage" potential of Github that inspired me to write this post in the first place. Github's obvious main draw is their freely available services to version control your source code repositories. While that is promising, I believe the real value might actually more so be residing in the various auxiliary services around your source code repos.

For example:

You can create Issues on a repo that would typically indicate a feature request or bug report, but someone took it and turned it into a backend for a URL shortener!
You can create Gists or small, miscellaneous code snippets that are simple enough to not merit an entire Git repo. Someone took that and turned it into persistent storage for serialized tabletop RPG character data!

Beyond that, you have Wiki pages that provide document storage. You can create a Project board on a repo that can hold bucketed text data.

All of this is of course backed by Github's ever-improving developer APIs.

And Beyond…

I found all of these hacked "database" solutions while browsing people's random side projects on Github and reading articles on Hacker News. It helped me appreciate the opportunities we have to build on all the freely available services around the internet.

Working With Sanjay

2025-04-20T00:00:00Z

This document should serve as a concise artifact that describes my style of work and leadership. It should serve as a quick way to get up to speed with what to expect as a new colleague or member of my team.

I am a strong believer in the merits of documenting, not just discussing, complex ideas for the purposes of clear and unambiguous communication. This document aims to provide an evergreen primary source of reference for my professional working style. The exercise of authoring and maintaining this document both helps me to introspect about myself as well as be transparent with those that would benefit from quickly understanding my motivations, strengths, quirks, and general style of work. The result for you reading this document and subsequently working with me should be less time spent having to figure me out as a colleague or leader and more time spent on solving interesting and difficult problems together.

I expect that this document should change and evolve with my capabilities and values as a leader and professional. Moreover, I expect that the content and change history of this document should remain fully transparent and public for anyone to look up and reference at-will. Any individual who has worked with me and finds an opportunity to improve the document should be able to contribute their own proposed edits in an opensource model.

The format of this document is a combined adaptation of the blog post by Miguel Carranza titled Working with Miguel and the Manager README by Oren Ellenbogen.

Who is This Document For?

Members of my team directly reporting to me
Members of my broader team not directly reporting to me
My colleagues and coworkers
Any leader who might want to use this as a reference for their own "Working With Me" document

My Mindset and Values

I am a very driven and self-motivated professional whose primary passion is people leadership on teams working on software and software-adjacent projects. Nothing brings me more satisfaction than solving hard problems in collaboration with other motivated individuals. I derive more joy from the wins of the members of the team than I do anything directly attributed to myself.
I try not to let titles or organizational hierarchies get in the way of professional relationships or impede the accurate flow of information and ideas. If I am throwing a title around, it's probably in service of removing a blocker or defending a position for my team.
I always enter a new professional relationship with the assumption that you have the best intentions and will put forward your best work and true self. I am an inherently optimistic and trusting person. My trust usually begins as a bucket more than half full. It is easy to fill it up but it is just as easy to drain it. More trust equals more autonomy in our professional relationship.
I believe that every member of my team should have an intent and responsibility to deliver at the highest level, both for the bottom line of the organization, and the culture of our team.
I believe in a culture of constant learning, improvement, and innovation. Learning also comes with teaching, and I expect those at a certain level of experience and seniority on my team should be a source of learning for their teammates.
I believe mistakes are ok and will usually be forgiven unless they are left without follow-up or action to prevent and learn from.
I do not hold much value in personally being “right”. I would rather be wrong as a step to the right answer or solution. I will always change my mind on something given opposing data.
I enjoy being surrounded by people that are smarter and more experienced than I. This means I have the most opportunity to learn from my time with them.
I value giving and receiving immediate honest feedback. I'd rather hear about it or provide it 1 on 1 while the moment is fresh in our mental context than at a later, “designated” time.

My Role

My current role is one that is fully remote with the following focuses:

Consistent, predictable, and efficient delivery of business value through software
Development and organizational alignment with a set of core business strategies
Support and professional development of my team

The majority of my work deals with supporting others with their delivery and a minority of my focus is on direct delivery of work products. I am commonly the middleman for the people leaders of individual contributors and senior leadership.

How We Will Work Together

This section is primarily for those directly reporting to me.

Regular check-ins: I favor near daily interactions, especially with those directly reporting to me and while I'm working fully remotely. I like to keep a weekly cadence of more formal project check-ins with a meeting and corresponding shared artifact we will maintain together.
1 on 1s: I consider setting up 1 on 1s with my direct reports to be my responsibility so expect those invites to come from me. I aim for weekly, 1 hour meetings. I will generally bring a prepared agenda which I aim to share ahead of time via shared notes (see below). You will generally always have the floor first for your agenda so try to come prepared with what you'd like to discuss. Not every 1 on 1 will strictly be work related and I generally like to maintain an overall balance of serious and casual agendas for these.
Shared notes and plans: I have a terrible memory due to my tendency to context switch a lot and have to rely on my own personal note-taking system to stay organized. I am a BIG fan of shared notes with direct reports for things like recurring meetings agendas or documenting ongoing, complex work threads. Slack Canvases are my current favorite for this, but I will adapt to whatever system you find most frictionless.
Communication: I am most comfortable chatting over text DMs. My meeting time is generally fully booked, so outside of regular 1 on 1s, please try to get your comms to be over chat. We can always punch out to a meeting but if you're asking me “are you free to chat real quick” the answer 95% of the time will be “no.”
Escalation: for immediate emergencies, favor speed over polish. If you're not sure if something is an emergency, always assume it is and let me know ASAP
Team support: I am always open to joining and providing support in group chats, emails, and team meetings. If you invite or copy me, please make it clear if you want input or attendance, else I will assume these are being sent to me as informative FYIs.

My Communication Style

I currently work fully remote. I've had to be very deliberate about the styles and modes of communications I employ to filter out noise and optimize the time I exchange information with my team.
Most interactions I have will be over an asynchronous text medium like Slack or email. Get comfortable with typing a lot and clearly communicating via text if you want to keep in touch.
I like to reserve face to face conversations for agendas that most benefit from them such as 1 on 1s, brainstorming, or complex decision making.
If you send me a DM, the notification might get lost and I will forget to respond. Please do not hesitate to bump the relevant thread if you're feeling blocked or stuck due to my non-response. I will always appreciate the reminder.
If you need to set up dedicated time with me, please consult my calendar availability first. If you're not able to find a suitable time, feel free to reach out and ask as my days can be back to back. I can usually shuffle things around as needed. Please include an agenda on the invite.
If you copy me on an email, add me to a group chat, or include me on a meeting invite, please let me know what action you're expecting from me. If the inclusion is only informative or requires some input, action, or preparation from me.
I like to think out loud. The basic act of communicating with you usually helps me work through problems and allows me to help you work through them better. The more you talk to me the more I'm going to be thinking about the things that can help you.

Things I Like

A proactive mindset. I expect that every conversation about a problem should come with some next steps or options.
Working out in the open. I love to see things that are “work in progress” on the path to a finalized state. You don't need to come to me with a fully baked plan or even a starting point. This helps you receive early feedback from your team and makes it easy for me to jump in if you need my direct support.
Concise communication. Get to the point. Tell me what you need or what the point of the conversation we're having is up front.

Things I do Not Like

Not doing your homework. My team members must take advantage of all resources available to them ahead of bringing a problem to me. If I could find the information you're asking for faster than you asking me the question, I will call you out on it.
Not following up on things that you've been asked to do or have understood expectations for delivery. I may ask once for a status on something (see quirks below “I'm a very impatient person”) regardless of your proactivity. If I ask twice, you should ask yourself what you didn't follow-up on and address it quickly.

My Strengths

aka. where I can probably help you the best

Team recognition: Have a team or individual that went above and beyond or reached a major milestone? Pull me into a standup, have me sign a formal recognition you authored, ask for suggestions for how to tell our people they did a good job and that we appreciate them for it.
Networking: are you working on a hard problem that requires some cross-functional collaboration? I can help you either find the information, suggest some ways how to find it, or directly connect you with someone who can help.
Brainstorming: feeling like you're drowning in ambiguity and don't know where to start? Schedule some time and let's just talk through it.
Being challenged: need something to push yourself out of your comfort zone and accelerate some personal growth? Just say the word. I'm generally thrilled to share something off my plate. But I will expect nothing but top effort on these. Don't come with this request lightly.

My Quirks and Growth Opportunities

aka. where I will probably need your help the most

I can be a very verbose and wordy person. If I am ever unnecessarily dominating a conversation or talking around the point, please interrupt me or call me out on it
I tend to overcommit myself. Sometimes this impacts only me and I bury myself in obligations outside of what you might need from me. Other times it might directly impact you. Either way, I'd like to hear the feedback if this happens.
I have a pretty short attention span and am somewhat addicted to context switching. If you need my focused attention on something, it always helps to concisely set the context for me in a conversation and state what you need.
I tend to be a people-pleaser and favor outcomes where all parties are happy. This can impede me from having direct and difficult conversations where there is a clear “winner” and “loser.”
I'm a very impatient person. I am always looking for the shortest path to resolution or quickest set of words to the point. If a thought or question pops into my head, I will voice it, sometimes without consideration for your mental context or status simply due to my impatience.

Coding with Copilot - Rewriting My Personal Site Using Generative AI

2025-05-09T00:00:00Z

This year, with the buzz of GenAI's burgeoning capabilities as a pair programmer looming large over my industry, I took the opportunity to find out whether the hype was real. I rebuilt my personal website from start to finish with GenAI and augmented coding assistance at the forefront of my approach. You can see the results for yourself (you might be reading this very post on the new site!), but the whole experience was nothing short of eye-opening. I can firmly say I’ve had my "ah-hah" moment with this new category of technology and came out of the experience a believer. I now know Generative AI–assisted software development is the future. Let me explain.

Why Rebuild?

I've had a personal website for many years (again, you might be reading this post on it!). I use it for a few main purposes:

Satisfying my need to have a space on the internet that's mine
Having a sandbox for tinkering with new tech
Having a purposeful outlet for keeping my technical skills sharp

Up until the beginning of 2025, the previous version served the first purpose well, but the remaining two were woefully unaddressed. Specifically related to the third point: due to the increasingly administrative nature of my day job, I hadn't been able to exercise my web development skills in years. So I used the task of a full rewrite as a way to get back to fulfilling all three goals again.

As the new year rolled in, I had a few concrete goals for the site:

Move off Gatsby as the frontend framework, since it had started to feel too heavyweight in terms of maintenance for a relatively simple site.
Migrate my blog posts from Medium, which had previously been my go-to publishing platform—and use this as motivation to revive my writing habit, which had stalled after a decent hot streak about four years ago.
- I also wanted an RSS feed for the blog that interested readers could subscribe to.
Refresh the layout and styling. Tailwind CSS had been on my radar as a solid and mature option—so I decided to finally give it a go.

I had been meaning to do this for months. But every time I sat down to make progress, I’d get bogged down with errors and obscure issues that killed my momentum and motivation.

Setting the Stage: Tools and Stack

I discovered the 11ty static site generator after stumbling on another beautifully crafted personal website and blog via Hacker News in late 2024. I was immediately impressed by its out-of-the-box simplicity and minimalism—combined with powerful extensibility via plugins and configuration.

I paired 11ty with Tailwind CSS as the styling framework and continued hosting via GitHub Pages on my custom domain.

Then, of course, there was the question of AI assistance. Like many, I first experimented with ChatGPT in late 2023 when the GenAI boom was just taking off. While it had improved significantly a year later, I quickly grew tired of copy-pasting between my editor and the chat interface.

Luckily, right as I started the project, GitHub released Copilot Agent Mode, which was already integrated into my long-time IDE of choice: VSCode. With 50 chats included in the free tier, the decision was easy—and I was ready to get started.

Laying the Foundation: AI by my side

TL;DR: Zero to...something, VERY fast

I was (and still am) building my prompt-writing skills, so I started with something simple that I figured a mature-enough LLM could handle: a scaffolding task. I knew that LLMs generally perform better with upfront context, so I carefully detailed my objectives:


I'm building a personal website. I'd like to build it using the 11ty static site generation framework and TailwindCSS for styling. It will be statically hosted on GitHub and served via GitHub Pages on a custom domain. The site will mainly be comprised of a homepage with a profile picture, title header, and small mission statement. Under that will be a short list of links. The site will also include a personal blog of posts authored in markdown format. Each post should include tags and a reading time estimate. The style of the site should be minimal, with dark greys and blues as primary colors and orange as the accent color. The font used should be Nebula Sans. Please generate all the necessary files and folders as a starting point for this project based on the specification, along with a list of next steps to build on the starter code, including how to deploy the website.

The response gave me this structure:


my-website/  
├── package.json  
├── .eleventy.js  
├── tailwind.config.js  
├── postcss.config.js  
├── src/  
│ ├── index.njk  
│ ├── blog/  
│ │ └── sample-post.md  
│ └── assets/  
│ ├── css/  
│ │ └── styles.css  
│ └── images/  
│ └── profile.jpg (add your profile picture here)  
└── README.md

That was the first big "ah-hah" moment. I had a functional starting point in under five minutes. I had previously struggled to get even this basic scaffold set up on my own—mostly due to Tailwind’s finicky integration with 11ty. The model opted for a prior major version of Tailwind, which made the setup smoother—something I hadn't figured out despite all my Googling and GitHub spelunking. Being able to finally focus on features instead of debugging boilerplate was thrilling.

I could’ve stopped there and continued coding as usual, but I was determined to see how far the Copilot Agent could go.

I worked through changing the layout, navigation, and styling, and added features like the RSS feed. From idea to prompt to working code, I saw a surprisingly high success rate. While not perfect, the model was usually able to fix its own errors when I fed it logs or observed behavior.

Eventually, I had it generate a basic GitHub Actions workflow to deploy to GitHub Pages—and just like that, the new site was live.

Where AI Fell Short

TL;DR: Clear requirements = smooth results. Ambiguity = chaos.

Sometimes, the LLM went completely off the rails and broke the codebase so badly I had to stop and roll back everything. The common pattern? Ambiguous requirements.

If I provided a vague prompt, the model didn’t take the MVP path—it tried to do everything all at once.

Examples:

I asked it to “improve the SEO for the site.” The agent went on a spree: rebuilding metadata, changing layouts, making 35+ file edits—none of which I asked for. I had to stop it and revise the prompt with constraints like "only add meta tags" or "do not change layout."
I prompted it to add basic functional testing but didn’t specify pages or scenarios. It chose Playwright—a great tool—but scaffolded a broken setup and couldn’t fix the errors it caused. I had to guide it through corrections and eventually forced it to stick to the basics.

Unexpected Wins

TL;DR: Bridging the gap from "this is a cool idea" to "I know it can be coded but I don't know how"

One of my goals was migrating blog posts from Medium. I started by exporting them as HTML files using Medium’s built-in tool. Then I asked the agent to convert them into Markdown and add them to my new blog.

The conversion quality dropped as the number of files increased, but unexpectedly, the LLM generated relevant tags for each post—something that didn’t exist in the Medium versions.

This led to another big win: my site now has a tag cloud. It visualizes all post tags with sizing based on frequency, and clicking one filters to relevant posts. I was able to clearly articulate the concept and desired templating, and the model generated working code in a single iteration. What would’ve taken hours manually took minutes with GenAI. Easily my second-biggest "ah-hah" moment.

Lessons Learned

To keep it short and sweet:

You can’t move faster from nothing to MVP than with GenAI by your side.
Be specific. Add constraints. Ambiguity leads to hallucination and runaway iterations.
The biggest value is when the LLM bridges your mental gap from idea to implementation—especially when you know what’s possible but not how to code it.

Final Thoughts

My experience with GenAI pair programming was transformative. I can’t imagine going back to coding without it. The ability to turn an idea into a working feature in minutes feels like a superpower.

My to-do list is now full of ideas I’m excited to tackle, because I’m no longer intimidated by how hard something might be to implement.

To anyone still skeptical: jump in. Start with a problem you care about and give GenAI a chance to amaze you. You might just have your own "ah-hah" moment.

“Enjoyed this write-up? Share it with a friend who’s curious about AI tools.”

Minecraft DevOps - Foundational Cloud Skills With a Fun Payoff

2025-06-23T00:00:00Z

I have been self-hosting a fleet of Minecraft servers on and off since around 2022. Through the process, I've been able to build and maintain a broad array of Cloud DevOps skill-sets. I have been leading a portfolio of Cloud Platform Engineering teams for the better part of 3 years. The position of leader didn't afford me much, if any, time to be hands-on with the core technologies that my team of highly skilled and specialized engineers leverages daily to get their work done. Minecraft and it's built-in offering to self-host multiplayer servers provided the perfect excuse for me to dump some time and a few bucks into a public Cloud service to host my own multiplayer server for my friends. Through the process of hosting my own Minecraft server, I was able to build decent competence in DevOps skill-sets. I was also able to get back to some of the core software engineering and web development skills to support this gaming hobby for me and my friends.

I have been playing Minecraft since college. I purchased the game back around 2011, past when the original fan-base had established itself, but well into when it was locked into its mainstream phase. I spent many hours playing with my friends and classmates on the shared server hosted by the university's Minecraft club without really thinking twice about where or how the server was running. Over a decade later, with a computer science degree and multiple years of working on enterprise technology, I gained the knowledge and experience to tackle the subject right when it was something I was interested in doing outside of work. At the time, I was playing with a few friends on a free, private Minecraft multiplayer server hosted on a website that seemed to be primarily funded via ads. It was clear that the instance we were playing on was running in a shared environment with very few resources allocated per instance. My friends and I eventually got fed up with the limitations of the service and the ensuring hit that the performance issues had on our experience. One of my friends, who happened to get their hands on a retired datacenter server rack, decided to be the first to take the plunge and self-host a server for us.

Unfortunately, this setup started to show its limitations pretty early. My friend didn't have the greatest internet connection and we constantly suffered from connectivity issues during our play sessions. He also did not keep the server running continuously due to how loud it was and not having a place to tuck it away at his house. That meant if he wasn't able to physically access the machine to turn it back on, we were out of luck on being able to play together on our Minecraft world.

I decided to take it upon myself to create the new and improved iteration of the Minecraft server for us.

The initial requirements, if you want to call them that, were simple:

A private Minecraft server accessible by only our friend group
Enough resources allocated to the server where we could all play on together and grow the world map significantly without causing server performance issues

I hadn't had a chance to apply my DevOps skills on AWS up to then, so I decided to select it as my Cloud provider for the project.

I spun up a modest t2-micro instance and got to work getting the server spun up. I did some initial tinkering to figure out how to get the Minecraft server process working on the VM. From there, I spent a little more time understanding how to create firewall rules that only allowed our specific IPs to access the server. Finally I did some simple systemd configuration to automatically start the Minecraft server on boot. Just like that, I had an MVP Minecraft server up and running on AWS.

I created a couple of Lambda functions to handle starting and stopping the instances and exposed them via HTTP GET API Gateway endpoints and provided those to my friends.

With just this MVP setup, I was surprised at the amount of general knowledge I acquired through the process. That, alongside the satisfaction of seeing the direct results of my efforts and being able to enjoy it alongside my friends, was a very fulfilling experience. I was by no means an expert or even moderately proficient at DevOps on AWS, however down the critical path of getting the MVP up and running, I was able to gain basic practical knowledge about

EC2 machine types and VM provisioning process
EC2 Security Groups and firewall configuration
systemd services
S3 bucket configuration and integration with EC2
IAM roles and policy

As we continued to use the hosted server process, I was able to iterate over the offering via ideas I had for how I wanted to improve the experience and requests for new features that my friends asked for. Some of these included:

Adding a custom server domain with dynamic DNS that updated the CNAME on boot since, without a reserved IP, the server would have a new IP on each boot. This way, instead of having to connect to a new IP each time, we could set the domain once and let the dynamic DNS handle reconfiguring where it pointed each time we booted the server via a crontab configuration.
Adding a Cloudwatch alarm that automatically shut the server off if it was running for over a certain number of hours per day to prevent unnecessary cost in the case someone forgot to shut it off after a session
Adding a Lambda function that would initiate a Minecraft world backup, upload to S3, and make it available to download

I was even able to branch out into my core software engineering and web development skills. I built a simple web portal where server status (running or stopped) could be displayed and controls to start and stop the server were available in a UI interface instead of directing having to hit an API endpoint. I was able to host the site for free using one of many hosting services for which their free tier was most than sufficient for my needs.

You can see a diagram of what I have working today below:

I got the whole architecture implemented in Infrastructure as Code via a combination of Terraform and Ansible scripts. My friends and I liked to spin up new server worlds when a new version of Minecraft was released or if we wanted to experiment with mods. Via automation, I was able to bring the total time of getting a brand new server setup from scratch, fully integrated into our admin portal with all the mentioned automation, down to about 15 minutes.

I initially considered going down the Kubernetes path for the infrastructure, but in retrospect I'm glad I didn't. I didn't want the required maintenance and upkeep of the infrastructure to outweigh the amount of time I could spend actually using it and enjoying it playing Minecraft. This was one of the key objectives of the project that I didn't know then but I can articulate now. Raw Kubernetes has a high cost of entry and requires decently large efforts to upkeep. More managed solutions weren't cost effective for my use-case where I was only interested in spending a maximum of a few dozen dollars a month.

My friends and I don't play Minecraft nearly as much as we did as our lives all got busy. But I wanted to share a little about the experience I had exercising my Cloud DevOps skills in this little project that was a pretty fun crossover between my professional and personal lives.

GenAI Augmentation for Technology Leaders

2025-07-10T00:00:00Z

I constantly encourage my teams to leverage Generative AI (GenAI) in their daily work. It's a powerful way to offload manual toil, allowing them to focus their mental energy on higher-level creative tasks and shrink the gap between an idea and its realization.

There are countless GenAI techniques geared toward individual contributors who spend most of their time building, configuring, deploying, or maintaining systems. However, as a leader, my day-to-day looks quite different. I dedicate very little time to individual contribution tasks. The vast majority of my time is spent collaborating, planning, aligning, tracking, and, generally, addressing the challenges faced by the people interacting with technology. This means I need a more novel approach to discovering how GenAI can benefit me and my peers.

That said, I truly believe in this technology's transformative potential. I also believe in practicing what I preach. Over the past six months—which is when I truly integrated GenAI into my regular work toolkit—I've discovered several use cases particularly well-suited to GenAI augmentation.

I'm excluding scenarios that are now ubiquitous and often built directly into email and video chat software. Examples include rewording emails for conciseness or tone, and automatic meeting transcription and note-taking. While these uses of GenAI are incredibly beneficial, they're not particularly interesting to discuss at this point.

Reviewing contracts

Several times a quarter, I receive contracts outlining work engagements with collaborating partners for my team or project. These documents can range from a few pages of boilerplate text requiring minimal attention to dozens of unique, complex pages. The agreement's context might also include specific details that, if not highlighted amidst dense paragraphs, could significantly impact the initiative. I have nearly zero legal experience, and while I work with legal partners who can review agreements from a purely fiduciary perspective, only I possess the context necessary to connect the dots to the underlying tactical and financial outcomes. Using a GenAI tool to summarize key points and discuss the agreement in the voice of a legal professional has saved me tremendous time and effort across multiple contract reviews.

Team working agreements

I believe all engineering teams should maintain a team working agreement. The best way to draft an initial version is to adapt one from a similar team within your organization. If that's not possible, a GenAI tool is easily the most effective way to generate a solid first draft quickly. When doing so, be sure to provide appropriate context, such as team size, locality (in-person, hybrid, remote, number of time zones, etc.), core working hours, tech stack, planning cadence (yearly, quarterly, etc.), and agile process (Kanban, Scrum, etc.), if applicable.

Summarizing weekly team accomplishments

Each week, our leadership team must summarize and roll up accomplishments or blockers from the previous week. Witnessing firsthand the improved quality of updates from my leaders who leverage GenAI for this task has been astounding. A key enabler here is the gradual improvement in tools that can connect to engineering backlogs, gleaning insights about completed tasks while integrating context from other sources like team correspondence via email or Slack, and internal documentation. I've even received direct feedback that using GenAI for this weekly task highlighted details a leader would have otherwise missed unless they meticulously reviewed every Jira ticket and Slack thread from the past five business days.

Authoring BPMs from incidents

When systems break and involve numerous people and systems, it can be daunting to reconvene after the dust settles and organize the past chaos into a coherent Blameless Postmortem document. Now that virtually every virtual meeting can be fully transcribed and combined with a Slack channel summary almost instantly, adding context to perform these tasks in the voice of an Incident Manager and generating the output in an enterprise-ready BPM structure becomes trivial. I've actually found this technique more useful for incidents I wasn't directly involved in. Being on the call and hearing all the context firsthand reduces the augmentation's boost. However, if I'm on the outside looking in, I can piece together key insights like business impact and "no-repeat" suggestions with a few well-crafted prompts. This is invaluable for systems outside my direct scope of responsibility but perhaps a critical dependency, or even when someone casually asks me what happened with a system that was degraded last week.

Codebase analysis

While I don't spend as much time in the code as I used to, as a leader, I'm deeply invested in key aspects of the code my team creates and maintains. I trust my smart team members to uphold proper coding standards, but in some cases, I use GenAI tools as a forensic aid to understand where code content might be contributing to unwanted friction or negatively impacting key outcomes for my teams. There's no shortage of static code analysis tools that already do this effectively. However, similar to my example of contract analysis, the real novelty of using GenAI here is its conversational interface. Instead of simply viewing a static code analysis report that assigns a one-dimensional letter grade to codebase "quality," I can have a conversation about the codebase. I can inquire about the multifaceted elements that contribute to its overall quality from the perspective of where I observe or hear friction within the broader human and technology systems.

Prototyping

This might be the use case most likely to be scoffed at by senior engineers. For those who are immersed in code daily, I understand that the gap between an idea and working code is far smaller than it is for a leader who only gets to write a few lines of code in their free time a couple of times a month. To that senior engineer, I say: I've been there and completely understand. But now, with my coding reflexes dulled over multiple years outside individual contribution, there's nothing more satisfying than translating an idea I conceptually know how to code into a working prototype in a few minutes instead of a few frustrating hours. I most commonly use rapid prototyping when explaining a design concept; rather than whiteboarding it, I can quickly whip up a low-fidelity working version in about the same amount of time.

I might do a second edition of this "use-case log" in another six months, as further experimentation yields additional valuable scenarios from the engineering leader's perspective. Please engage if you're interested.

My Professional Productivity System

2025-08-14T00:00:00Z

I've spent the better part of the past decade as a technology professional, moving up and across multiple roles of software engineering and leadership. Through the years, I've built up and refined a personal set of organizational tools and processes that I feel has grown with me through my career and continues to drive consistent, positive outcomes for me.

Core Strategies

My professional organizational system is founded in a few core tools that are used in specific processes for highly targeted objectives.

Low friction in and out of the system (i.e add an item to the todo and identify what to do next)
Quick setup and zero maintenance
Maximizing delegation of mental load

These objectives weren't something I started the process with, rather they naturally emerged as I built my processes around the core things I found necessary to be successful and scale my productivity as my scope of responsibility grew.

Tools

The shortlist of tools and processes that I will expand on below goes as follows:

TODO List that is synced across all devices with low friction in and out and basic additions like scheduled task recurrence and "follow-up" statuses
Email flagging for follow-up action
Slack chat reminders and TODO list integration
Written Notes
Visual Notes
Calendar

TODO List

Let's start with the backbone of my productivity system. If it's not on the todo list, there's no guarantee it's getting done. I've managed to build a pretty strong habit of putting things into my todo list the moment a task becomes my responsibility, no matter how insignificant or quick I feel it might be. If you're ever having a conversation with me and an action item hits my plate, it's very common for me to pause and vocalize as I add an item to my todo list before continuing the conversation. The top priority "features" of my todo list include:

Quick accessibility to the task inbox anywhere anytime so I can document tasks as they come to me in a single action (Alt-tab to another window and hotkey press or two taps on my phone)
Automatic syncing across all my commonly used devices (primarily my work laptop and personal phone)
Option to add notes and subtasks on entries (sometimes the task needs additional context to effectively recall and act on)
Option to mark a task as needing a "follow-up" and filter on those tasks (In the case that I'm waiting on a dependency or delegated it to someone else but am still accountable for it)
Ability to have tasks that repeat, on a weekly or monthly basis
Ability to set priority order and deadlines for tasks

Email

Moving on to what some might consider the necessary evil that I've had to wrangle into my process. While many organizations might have shirked off email as a primary means of asynchronous communication, it remains a core necessity for smooth cross functional communication for my work. The volume of emails I receive daily has increased linearly with my scope of responsibility while the percentage of emails I actually need to spend focused time on reading or responding to has steadily shrunk. I'm also a stickler of maintaining my inbox at zero unreads. This leaves me in a scenario where I'm able to scan through my unread emails in a fairly short amount of time but I need to set aside a small subset of emails for later action.

I leverage the "flag email" function as a way to mark these emails that I have read and identified as requiring a follow-up of some kind. Filtering on these marked emails presents me with another neatly organized todo list of sorts where the default order of priority is in reverse chronological order. I typically don't let this list of flagged emails grow to more than a handful of entries and generally I like to close out actions for flagged emails within the same work week.

Slack

Working remotely, a majority of my communications and related organization happens via my primary, asynchronous chat software: Slack. Luckily for me, there is a growing suite of productivity tools that integrate easily within Slack. I find myself spending more time in the software and looking for every opportunity to consolidate another one of my productivity tools into it. This, like email and my calendar, is primarily driven by the network effect that most of my coworkers are also on Slack.

Like my email inbox, I aim to have zero unread messages in Slack to a fault. This necessitates a couple of techniques to ensure that something I read that requires an action doesn't get forgotten. First and simplest is the Reminder. I most commonly will use the "remind me in 3 hours" feature if I can't get to a reply immediately but expect I could later that day. If someone can wait till tomorrow or the following week, I set the reminder with the conveniently available options accordingly. In the case that I need to review all the items I've set reminders for, I just go to the "Later" tab in my Slack sidebar as another list of todos to review as needed. For scenarios where the follow-up action might be more complex or take more focused time, I use the "Send to List" feature where the list in question is my TODO list mentioned above.

Written Notes

My private written notes are, for the most part, a minimally organized spread of markdown documents that I author and index via my current note-taking app of choice: Obsidian (coincidentally it is where I'm writing this post, as it is also my primary tool for digital writing).

This is the part of my productivity system that I've spent the least amount of time refining since its usually where I spend the least amount of time focusing or referring back to during my work week. This might be a side-effect of my working style being relatively shallow in its day-to-day cadence, focused mainly on information and decision making I'm able to manage mentally or via delegation. Yet without the repository of critical information available for quick additions and recall, there would be a significant gap in my overall system and would add enough mental overhead to cause other parts of my system to begin to fall short.

Most of my notes live at the root level of my Obsidian vault. There are only a few top-level folders I use with no secondary level of organization to any of them:

1 on 1s: A single note per individual I have recurring 1 on 1s with. These get used most with my direct reports and reporting manager, with whom I meet at least once a week
Weekly status updates: dated entries with aggregated and summarized updates from all the teams and projects I manage
Recurring meeting agendas: for tracking topics of discussion for meetings I have on a weekly or monthly cadence

For public note taking, I have been increasing my use of Slack Canvases for written documents that serve a more collaborate purpose. It similarly supports native markdown syntax and integrates seamlessly with the rest of the Slack ecosystem of features. The lack of any sort of hierarchy or grouping function hints at the limited scalability of this feature over long periods of time. I am weary that the process of exporting notes out of a set of Canvases will probably be frictionful, so I try to keep evergreen notes that I expect to refer back to in the long term in Obsidian and isolate Slack Canvas notes to only those who's purpose is primarily for sharing and asynchronous collaboration.

Visual Notes

In some cases, visual notetaking is a better fit for the topic I'm trying to articulate for myself or share with others. I'm a big proponent of the "boxes and arrows" method to translate a concept that is best captured visually rather than in spoken or written words.

I maintain a single "public whiteboard canvas" in Miro split up into multiple, independent, simply-titled Frames where the content of each frame is analogous to a moment where I might have grabbed a marker and scribbled an aforementioned set of boxes and arrows on a whiteboard. The main difference and sometimes advantage of this exercise happening in an easily sharable and digitized space first is that I don't have to worry about taking a poorly lit smartphone picture of the whiteboard at the conclusion of the discussion where the only shareable artifact is the photo, then copied and pasted ad-hoc when needing to be recalled.

I also have a private version of this infinite canvas where I can do similar exercises but for scenarios where the topic might be private only to me or sharable to a select set of individuals.

I'm trying to find a method to effectively index all of these individual whiteboard frames and bring them into the quickly searchable context of my other written notes which I can already fuzzy search through via Obsidian's command pallet in a few keystrokes. I'm aware of Obsidian's Canvas feature which might serve the purpose but I need to explore further to determine how the use case of sharing with coworkers would work.

Calendar

My calendar is primarily used to determine when my time is occupied with meetings as an opposite tool to my todo list. My days are generally organized into either "meeting time" or "task time" which I further subdivide into periods of long focused work, short task time, or breaks depending how my day or week is playing out. I haven't found much value in scheduling my day further than with respect to the time that I explicitly need to coordinate a meeting with one or more other people, most commonly my coworkers.

If I'm scheduling meeting time with my coworkers, which is the majority of my scheduled meeting time, then it falls to my trusty Outlook calendar, which I've used for years for no other reason than it's what my coworkers are using. If the meeting time has something to do with my personal life, then I'm reaching for my Google calendar.

The day is usually peppered with enough unexpected interruptions or meetings that extend past scheduled time to where this ability to flex the rough edges of the schedule naturally became one of the things I needed the other parts of my process to accommodate for. If I have a block of time that isn't for a meeting, I can simply switch over to one of my todo lists and pick off whatever task is highest priority that I judge I can complete or make significant progress in the time I have. If nothing jumps out from the todo list or my brain is simply indicating that this time would be better spent not doing anything specifically productive, then its time for a break.

What's Next

I've become comfortable with the reality that everything I've mentioned above is far from some "ultimate" productivity system I'd see myself using for the rest of my career and life. This is a snapshot of what is working for me today, and with it I have a few things I would still like to make a bit smoother in my process to serve my core objectives.

(As mentioned above) Indexing and cataloging my visual notes so they are easily searchable in a single context along with my other written notes
Moving my todo list into a native text-based format with basic automation to support the critical integrations and features critical to my process integration (todo.txt is an interesting foundation for this idea)
Bringing my private and public written notes into a single system without sacrificing the outcomes of frictionless collaboration and continued easy indexing
Explore ways to integrate LLMs into the corpus of all these tools and begin to create more advanced automations to continue to offload menial mental load to the system and free up brain space for higher order thinking

'Isms - Tidbits of Wisdom I keep Returning To

2025-09-23T00:00:00Z

I spend lots of time speaking with friends and other technology professionals about a wide variety of topics from career advice, technology hype cycles, how to lead people, and finding success in our personal endeavors. Over hundreds of these discussions, I find myself returning to some of the same tidbits of wisdom that I reference with a short phrase or label. These ideas have been passed down to me or created from bits of my learnings and experience and synthesized into a concise concept in my own words. I don't claim to be the first person to have come up with these concepts, and I won't be the last, but I have personally gleaned a lot of value in internalizing them and continue to find opportunities to share them with others in casual discussion or mentoring contexts. This post is my attempt to document these tidbits of wisdom in an easily shareable format. I hope that you might read something here that resonates with your experiences, or some of that wisdom might be passed on to you.

They Have to Feel the Burn Themselves

We've all likely experienced something that caused such an acute sense of fear and stress that our primal survival instincts forces us into behaviors that do everything to try and prevent that scenario from occurring again. In professional life, those events might seem mundane and are nowhere near the life threatening perils humans evolved to protect against. But the power of fear and stress as a learning tool sometimes cannot be outmatched.

The most common context I return back to this phrase for usually revolves around technology professionals not having the proper appreciation for the discipline required to run production systems that have wide and significant impacts. That could be understanding why proper testing of new features or components is by far a better use of time and energy compared to debugging under the stress of production impact. Its the difference in understanding why its not ok to leave the issue alone till tomorrow and risk irreparable harm to your product brand instead of hunkering down and grinding through till it's fixed now.

The people I speak with that are frustrated when others don't share their urgent perspective on an imminent bad scenario are usually also those who have been on the receiving end of that burn. They remember the fear and stress and want nothing more than to avoid for themselves and their peers. I do believe there's merit in trying to teach via anecdote rather than resolving to throw newbies into the deep end to let them sink or swim. Unfortunately, sometimes they have to feel the burn themselves to truly understand and internalize the lesson.

The Career Identity Crisis

The "career identity crisis" is the point at which one must decide to pursue a path deeper into their chosen discipline or fork into an adjacent one to make forward or upward progress. In my chosen career path when I had the title of Staff Software Engineer, the decision was one of Principal Engineer, which demanded further specialization into software and systems engineering, or Engineering Manager, which took a path focused on leading technology teams. This fork in career path could be extended to any industry that separates the roles grouped into what might be labeled "individual contributor" from those of "middle management" and above.

I received advice early in my career that it didn't serve my interests to simply accept that I would enjoy and find success in either role. A trusted mentor advised that I needed to form an opinion on which one to specifically pursue, and by extension which to not pursue. In fact, they made it clear that I had to pick. Without deciding, those supporting my career growth would not know how to provide me with corresponding opportunities for each respective discipline. I experienced a sort of identity crisis grappling with this decision. Fortunately, I came out of the dilemma resolved and very happy with my decision. My personal experience helped me form this piece of wisdom that I've been able to recognize in others and share with them.

For those that at this fork in the road, I give the same advice I received myself. You have to decide. For the leaders that are responsible for growing those individuals into these respective roles, I encourage them to take advantage of the reality of the situation. Be plain about the need to decide, but curate distinctly different opportunities aligned with the different paths past the fork and label them as such. Make it clear which "type" of project or challenge you're offering and encourage the individual to be open to enjoying or not liking the experience. For example, I would give a staff engineer unsure of moving up to a Manager or Principal role different projects that I label as more "Managery" or "Principaly". A "Managery" task might be coming up with a career growth plan for a junior engineer or helping mediate an interpersonal conflict. A "Principaly" task might be designing and getting architectural approval for a new system design or integration of a new technology into a product. Let the varied opportunities inform their opinion and your curated labeling determine which path yields the best fit for them. Embrace the fork in the road knowing you can take a tour down each path before committing to the route.

Recognition has an expiration date

Showing gratitude feels like a cheat code for people leaders. It doesn't cost anything, and if done correctly it might be the most effective way to motivate and bring forth happiness. Regardless of the form of gratitude, whether a simple "Thank you" and "good job", or something formal like the presentation of an award, I've found that the magnitude of effect is directly proportional to the length of time between the act and recognition. A simple "thank you" right after the action generally has a stronger impact that any gesture after enough time has passed. As time progresses, the memory starts to fade, many other events begin to supersede the original, and a sense of the gratitude starts to seem like a lazy afterthought. However, I also believe that "better late than never" is a valid perspective on this scenario as well.

Take both extremes into consideration: let the urgency of the impending expiration date prompt you to action, but don't use it as a reason to give up even if you feel like too much time has passed.

Starting with a ball of clay

My style of working on complex problems is like how I approach writing: I slap down a simple draft as quickly as possible and do multiple iterative revisions until the quality of work is satisfactory. The emergence of Generative AI tools and their ability to play the role of brainstorming or thought partnership is how this 'ism formed. GenAI is extremely good at authoring a first draft from a rough concept. I compare the result to slapping an unformed ball of clay onto the pottery wheel. It is nowhere near a finished product. In fact it is barely on the first step to being one. But sometimes getting the first draft down can feel like the most difficult part of the process. Once you have it in front of you as a boost to your mental momentum, you can rest assured that somewhere inside the unformed and unremarkable material, the finished product does exist. The thing bridging the gap is the human process of removing, adding, shaping, forming, and detailing it.

You might flip the analogy in the other direction and compare knowledge work as an additive process, where a small kernel is added on to and progressively built up into the final product. Either way, I use this 'ism as a way to encourage people to not be intimidated by the idea of perfection and just get started. Use the tools at your disposal to get that ball of clay in front of you as fast as possible, then spend most of your time and energy sculpting it into the final product.

Pressure release

The work I engage in most commonly in my day-to-day is a constant battle of priorities and context switching. I have to decide, up to multiple times within a single hour, what is the most valuable task is to put mental energy into. Moreover, my personal priorities are not always perfectly aligned with those of my peers, stakeholders, team, and leadership. Commonly, I feel a lingering sense that a specific thread I am accountable for is building in pressure, whether external or internal, and usually driven by a sense of ambiguity, perception of being stalled, or general lack of confidence. Irrespective of where this topic sits in priority or how complex the task is, the longer that the core issue is left unaddressed, the larger it seems to loom over everything else.

I use the analogy of a pressure vessel that requires a release, for no other reason than to remove the background anxiety of its existence and increasing danger of the inevitable explosion. Venting just a bit of steam from the chamber gives mental space for other things, even if the action was largely symbolic. Sometimes it's worth it in the short team to release some pressure for the sake of the bigger picture.

If any of these tidbits of wisdom resonate with you, I'd love to hear about it from you. If I gather enough new ones, I'll consider authoring a "part 2".

Coding with Copilot Part 2 - Agent Edition

2025-10-28T00:00:00Z

I recently read a blog post lauding the experience of using Claude Code for Web. Specifically there was quote in the post that goes as follows:

I’ve been using it as a “to-do list that does itself” — when I think of something small that I want to tweak, across a variety of projects (work, work-related side project, side project, open source project) I just throw it into a thread. Then I come back, sometimes later in the day and sometimes days later, to see what Claude did and to finish things up.

I read this and thought "This is EXACTLY how I use AI for coding today" and it prompted me to start this post. In this post, I'll share how coding agents have fundamentally changed not just my productivity, but my entire approach to personal project management. Consider this a follow-up to my previous post, outlining my current workflow for getting the most out of the latest and greatest AI tools available for software engineering.

It's been almost 6 months since I started practicing AI-assisted coding and wrote about my very positive experience with it. At the time I had just started with a basic setup including Github Copilot in VSCode with Claude Sonnet 3.5 as the driving model.

Using Github Copilot alongside my standard setup in VSCode to work on coding projects (primarily this website) was a significant jump in my overall productivity and ability to deliver working software via augmentation. However, it didn't fundamentally change the overall workflow or cadence of how I came up with ideas, tracked them, worked on them, and eventually (maybe) shipped a finished version of them. Having AI in the passenger seat chopped the time to work on and ship the feature, however there were plenty of times that an idea just languished on my "coding projects todo list" until I got even 30 minutes to sit and focus on a coding session.

Enter coding agents. My first exposure to this paradigm came when Jules was modestly announced at Google IO 2025. I'm not deeply familiar with the history of "who came first", as far as I know Google Labs was the first to ship an asynchronous coding agent as a free, albeit "experimental," product. The user experience was incredibly simple and in a few clicks I had the agent hooked up the repo for my personal website and I was off to sending it prompts to work on for me.

After a few sessions with it, I could confidently say it worked 100% of the time...about 80% of the time. But I'm more than satisfied with that kind of hit rate on translating a few lines of plain English into working code. From there I threw it a few random tasks that I otherwise would have just thrown to Copilot but was simple enough to open up a browser, submit the prompt, and move on to something else without having to keep an editor open or monitor the agent's coding progress.

After a few months of light usage was when the paradigm shift happened. I thought up a new enhancement I'd like to have added to the site. I reflectively reached for my todo list to add it, but paused when I realized I could just pull up Jules in my browser and send it the todo instead. And so I did. I typed out my todo item in a few sentences, clicked submit, and watched Jules spin up and get to work. Suddenly , I felt like I was leveled up. I had just created a "todo list and does itself".

The next "ah-hah" moment happened after I received this lovely email from Mozilla about the sunsetting of Pocket.

I used Pocket to bookmark links to interesting things I found online and built a Github Actions-based integration that hooked into the pocket API and populated the Daily Reads section of my website homepage with links I specifically tagged to share. With pocket going away in the next few months, I had the task ahead of me to quickly find an alternative else some core website functionality would break.

So I gave it to my self-doing todo list: Jules. I started with the following prompt

Propose 3 plans to convert the pocket integration to other services that can be used to save and retrieve links via an api to populate the latest reads section

After some research and consideration via some other AI tools, including chats with ChatGPT and Gemini, I landed on Raindrop as my choice for replacement. And so I instructed Jules in the same task context (yes I included the typo from the original prompt I sent on purpose):

make the code changes to covert the site features that rely on pocket to raindrop io as outlined

Jules did it on the first try, nearly flawlessly. A full refactor to a completely new bookmark manager system and API integration, seamlessly swapped into my existing Github Actions integrations with the only real update I had to make was swapping out an API key. You can see the full Pull Request here. In total, Jules edited 8 files with around 100 lines updated. Unlike most other PRs opened by Jules, this one required zero fixes or additional edits after my review. This will probably remain the example that cemented my optimism for this being the next step in how AI will continue to change the game for Software Engineers.

Since then I've tried other hosted agentic coding products like Open AI's Codex and the recently released Claude Code for Web. Even though I find Claude's models to be the best at coding via Github Copilot or Claude Code, nothing I've used has matched the level of polish, quality, and accuracy that Jules has achieved for me thus far. I'm far from a power user, clocking maybe 1 or 2 hours of coding time a week, but from my experience its usually the product that can get it right quick and early that ends up holding its own.

As with most things, its not all rainbows and sunshine. As I mentioned, Jules gets it right about 80% of the time on good days. Even then, most PRs it opens requires at least a couple of passes of reviews from me and usually some final polish and tweaks via a local coding session with Copilot. In some cases the feature is simply too complex for Jules to handle and it will ship a completely broken PR that I end up just trashing and starting from scratch. Even with these pitfalls, my overall productivity is up another 2x. Tasks that would have taken 2 hours with no AI, went down to less than 1 hour with Copilot, and have in some cases gone down to minutes with Jules. My trusty todo list has literally been outclassed.

As I continue dabbling in these tools on weekends and free evenings, I'm looking forward to the next paradigm shift that is inevitably on the way that will let me do even more with less.

My System to Keep a Reading Habit

2025-11-30T00:00:00Z

I get asked how I stay informed as a technology professional when the industry seems to be moving faster than it ever has and the demands of staying informed to keep up have never been higher. In this post, I'll summarize what works for me so that it might inform you if you're curious and supplement your practice if you're looking to get better at it.

Reading is how I like to stay informed about the world as well as a hobby that gives me an opportunity to intermittently distance myself from my mostly digitally-driven life. At the time of writing, I'm one day away from a 365-day streak of reading at least one page of some kind of content every single day and I've read 40 books this year so far.

Reading for Information and Education

Here's the system I use to stay informed for targeted professional purposes. This section could also be considered the more "official" or "formal" side of my reading habit. I consider reading about topics related to my job and current world events to be enjoyable, however they're not a fully recreational set of activities or topics and lean practically towards my overall growth and development as a professional.

Below is the bookmarks folder I simply label as "Daily Reads". I (try to) go through these links daily or weekly depending on the publishing schedule.

Hacker News (daily) - HN is well known in the tech community as a sort of "front page" for the industry. It has a frontpage algorithm driven by reader engagement on posted links where the active userbase is strongly populated with the who's who of the tech and startup communities. This one has been at the top of my list for years and has consistently delivered a surprisingly diverse set of content not just focused on technology startups. The dialogue in the comments can skew a bit on the "snobby" side, I'll say—however the equally high intellectual and contextual rigor given to the conversation is pretty unique for internet forums at large. I've consistently seen popular links posted here on a particular day being ported to other publications a day or two later.
TLDR Newsletter (weekdays) - This one was pushed to me via targeted advertising on social media. I think of it as my "Hacker News supplement". The content is primarily tech focused and I can usually find at least one link that I already saw the previous day on Hacker News. But all in all, there have been at least one or two unique finds worth reading each day here to keep it on my daily reading rotation.
Kagi News (daily) - This is my break out of just reading about technology every day. There's a lot going on in the world each day and if I'd like to consider myself informed in a balanced way, I reached for a more comprehensive news source. I landed on Kagi News (then named Kite News) after rotating through the more "traditional" news publications including The New York Times, The Wall Street Journal, and other rising internet news publications including Ground News. The fact is, I am still experimenting here. I'm still trying to settle on a news source that I personally feel finds a healthy balance between reporting on the sensational mainstream, USA-centric news while including the underrepresented but equally important global news.
Software Lead Weekly (weekly on Fridays) - Rounding out the bunch is the focused curation into content centered around leadership and, more specifically, leadership in software and technology. Oren has built what I think is a valuable resource for technology leaders and consistently curates quality reading content from which I always glean something that helps me in my job and even my life (The progressive webapp version of the website is also really well done).

The list is driven by a few core objectives/strategies that inform what I'm trying to get out of the content:

The amount of total daily content should be easily read through, at least at a top level, in around 30 minutes. That would include deep reads of one to two links per source. The list could change and grow but generally if I'm having to read through more than five sources, my habit is probably going to fall off.
The content should inform me about my top 3 interests: current events, technology, and leadership. I'd like to receive these topics in a balanced way such that I'm not tunnel-visioned into just the topics that interest me but rather all those that give me the best, most informative perspective.
The content should be accessible in a deliberate way and not just pushed to me via an algorithm that prioritizes engagement over everything. If I'm not making some deliberate decision on what content I'm consuming, when, and how, it means that I'm delegating my outcome of being informed to something whose objectives are not aligned to my own.

Reading for Fun

This part of my reading habit has no objective to be directly practical or beneficial towards my growth as a professional. I reserve my reading list of novels, short stories, and other literature purely for things I want to read or that I find interesting or fun. Generally, I'll end up finding some learning or indirect benefit from these activities, but my going-in stance is pure indulgence and recreation.

My consistent reading habit and respectable number of completed novels this year has been enabled by a few strategies I've developed over just this year:

Always give myself multiple choices of what book I could be reading at any given time
Take advantage of all formats of books available to me (physical, e-book, audiobook)
Have easily accessible options on my phone as an alternative activity to scrolling a dopamine drip algorithmic feed
Give myself permission to ditch and not finish books that I didn't find interesting or engaging
To put these strategies into practice, at all times I'm in-progress on:

An Audiobook on Audible - A Pro Tip on this one: I use a "hidden" subscription option under the Premium Plus offering that gives one audiobook credit every other month since I found that one every month was too much and a waste of money for me
An Audiobook on Spotify - Premium Duo plan provides 15 hours of audiobook listening
An e-book on Kindle (Paperwhite and mobile app) - usually borrowed from my local library via Libby
A physical book

Having multiple books and formats to reach for makes it so it's incredibly easy to always get some reading done each day. Removing this mental friction and giving myself options to switch between different books has been key for me to building a consistent reading habit. If I happen to be around my physical book, I try to pick it up with the target of reading a page and generally end up reading more than that. If I'm driving, I pop an audiobook on. Even ten minutes a day stacks up to a lot of progress over a month. In pretty much any other scenario, I have my phone and an e-book is a couple of taps away just like any other app I'd otherwise fill my idle time and attention with.

To wrap up my thoughts: I came to this current reading system and gleaned its results through deliberate and consistent experimentation over most of this year. While scrolling algorithmic, curated feeds optimized to catch and hold my attention might have made me feel like I was reading more - it did not fulfill my desire to be more informed and mentally engaged with new information at a pace that my mind could meaningfully digest. That, balanced with the activity of reading for no other purpose than fun completes the objective of my overall system.

I hope this was insightful and informative for you, reader!

The post was authored with editorial (Claude Opus 4.5) and visual (Gemini 3 Pro) support from Generative AI. All words are my own.

Healthy Tension

2025-12-31T00:00:00Z

Every leadership decision about team composition is a strategic bet. You can prioritize short-term execution or long-term capability building, but rarely both equally. An important skill of leadership is building teams, or the ability to decide how to bring together a set of people to effectively solve a problem or achieve an objective. This skill can be applied at the smallest scale with just a single person selected for a targeted purpose, such as a team lead assigning a team member to a task.

This exercise in decision making can be scaled up multiple levels to larger and larger scopes of teams, where at some point the leader is no longer making decisions about assigning individuals to tasks, but rather organizing teams or groups of teams around a strategic priority. When you start to have to consider this scope of leadership in building teams and organizations to solve problems, a key trait that begins to emerge is what I've dubbed healthy tension.

Healthy tension, at its core, is as follows: the organizational dynamic that emerges from the decision of a leader by aligning a group of people or teams around a common set of goals while deliberately placing their strategy, tactical approaches, values, and/or priorities at odds with each other.

When building teams, the most intuitive trait to prioritize is strong collaboration and good chemistry. As a leader, you would prefer that your team, simply put, gets along. However, even in the smallest of scales (think a "1 pizza team": small enough to feed with a single pizza order, typically 6-8 people), what you don't want is a notion of "groupthink". Strong teams are built on a foundation of shared purpose but diverse approach and opinion. The best and most effective teams find ways to promote individual thought while working through disagreement in healthy and productive ways towards a common goal.

To better describe this idea, I'd like to describe a hypothetical organizational structure where a focused effort to have teams at odds with one another could be the right if not the best structure to achieve an objective.

A senior leader in charge of a factory responsible for producing "widgets" has been tasked by their shareholders and board to increase overall operating profits and reduce the amount of lost revenue due to defective product exiting the production line and having to either be trashed or returned by customers.

The leader has a decision to make. How to split up their team to effectively achieve the objectives laid out to them. The leader decides to organize their factory from the existing pool of employees into the following teams:

The Production team is responsible for the operation and functioning of the line are given the priorities to produce product as quickly and accurate to spec as possible. They are measured on number of product created to spec with any not created to spec not counting to the total. The spec is provided by the R&D team.
The Maintenance team is responsible for the upkeep of the production line machinery. They are measured on the overall availability and uptime of the machinery as well as how quickly they are able to perform repairs.
The R&D team is responsible for authoring the spec used by the Engineering team and built by the production machinery. Their priority is to do research to create the most innovative designs and push the boundaries of Widget capabilities to maintain competitiveness in the market.
The Accounting team is responsible for ensuring all operations are costing as little as possible without compromising on any of the other objectives.

Now consider the healthy tension present with this organizational structure.

The Production team:

Needs the R&D team to simplify their designs to make them easier to produce
Needs the Maintenance team to speed up their repairs so the line can be down for less time
Needs the accounting team to find a better balance on cost saving measures that don't impact the overall productivity of the line

The Maintenance team:

Needs the Production team to manage the pace of their work to not to require increased maintenance and repairs due to the high stress on the equipment caused by the high pace of production and ultimately leads to more issues, repairs needed, and downtime.
Needs the R&D team to consider the practical requirements of their "cutting edge" designs on the corresponding bespoke and hard to maintain production line equipment it requires.
Need the accounting team to consider the cost of their services, while indirect, just as critical to the overall organization's objective lest the production line be constantly broken and limping along without proper maintenance

The R&D team:

Need the Production and Maintenance teams to adapt to new designs quicker so that the company can iterate on the shipping the latest Widget and capture market share as quickly as possible
Needs the accounting team to stop cutting the research budget as a long-term priority in favor of the shorter term priorities of Production and Maintenance

This might at first seems like the most dysfunctional organization this poor, misinformed leader could have ever put together. But healthy tension in an organization can only be effective with a set of core values and strong team culture holding it together. A critical, uncompromising responsibility of the senior leader establishing the healthy tensions is also to set a culture of collaboration and shared success (and failure).

The teams in our fictional production company are also built with the following precedents and instilled with the following expectations along with their priorities:

Each independent group has to go into each challenge with the best intentions for their partner teams. They have to understand that one of their core deliverables is collective success. Success that comes at another group's expense isn't success at all. Therefore, they must find ways to collaborate and work out differences in opinion in productive rather than combative ways.
Each group is expected to come up with solutions in collaboration with their partner teams and not simply escalate disagreements to upper management unless it requires an explicit decision outside or across the scope of either group.

Now consider the benefits that emerge with the described objective, org structure, team priorities, shared core values, and expectations:

The Production team

Provides feedback to the R&D team on how to include adjustments to their upcoming design based on the practicality of production for the current iteration that finds a healthy balance between innovation and efficiency of production
Partners with the Maintenance team to create processes to manage the pace of the production line within tolerances of the equipment to minimize issues and subsequent repairs.
Incorporates suggestions from the accounting team for production methods that increase cost efficiency without meaningfully compromising on overall production throughput

The Maintenance team

Consults with the R&D team on more modern and innovative techniques to perform maintenance and repairs more efficiently
Provide the accounting team with measurable metrics on the return on investment for a robust maintenance process and routine

The R&D team

Researches new technologies and develops new processes for all other teams that the accounting team could directly relate back to return on investments and cost savings

If you have spent any time in a large, multi-disciplinary professional environment, you can likely map these fictional teams directly to roles in your own organization. The specific scope and resulting healthy tensions might vary, but I think its highly likely you could discern what your organization's version of this healthy tension might be.

In my opinion, the real strength of this dynamic is its inherent self-sufficiency. Assuming there is a set of core values that each member of the organization holds themselves to, the overall effectiveness of the organization scales proportionally to the collective strength of the independent teams. The higher the healthy tension, the higher the possibility and degree of success. As leaders, I believe we should all consider looking at our organizations, large or small, through this lens of healthy tensions and determine how to best configure it to be in balance and serving a collective objective. What tensions exist in your organization today that, if acknowledged and channeled productively, could drive better outcomes?

The post was authored with editorial support (Claude Opus 4.5) and image generation (Nano Banana 3 Pro) from Generative AI. All words are my own.

Human Debt

2026-01-20T00:00:00Z

Software engineers understand technical debt. It is the accumulated cost of trading off quality for speed or the short term for the long term that must eventually be repaid. Leaders have their own version of this ledger. I call it human debt: the relational cost incurred when you must sacrifice goodwill or trust to serve a higher priority.

Software engineers often have to make decisions around how to manage technical debt. They might consider large decisions such as bringing in a new and unproven component into their architecture down to the smallest consideration where every new line of code in the codebase is considered additional toil.

People leaders have to consider the currency of professional relationships as a key component of how effectively they are able to do their jobs. Similarly to the software engineer, who is optimizing for the highest quality within the tightest constraints such as time or cost, the people leader must optimize for tactical delivery or strategic victory potentially at the cost of favor or trust amongst their peers, subordinates, and superiors. In some cases, they must incur this human debt to effectively meet their goals or enable an objective for their teams and organization.

The Uncomfortable Reality

The consideration of deliberately damaging a professional relationship to further another objective isn't commonly discussed (as far as I've read). It is, however, something I've discussed many times with other leaders and peers. Just as shipping inefficient or buggy code for the sake of speed, for example, it is sometimes the difficult but correct decision a leader must make for the greater good of their priorities.

This creates tension between the prevailing leadership advice that is: build strong relationships, your people are your top priority, take care of your people and the rest will take care of itself. The nuance comes from when the "rubber meets the road", and you as the leader have to apply this advice in practice. You navigate a complex web of professional and interpersonal politics, biases, prejudices, grudges, favoritism, and selfishness. Prioritizing the people you work with sometimes means sacrificing the goodwill of some for the sake of others.

When Human Debt Becomes Necessary

There are some scenarios I will frame up based on my own personal experience as a leader that come to mind on this topic:

Moving a team member off a project they stood up and have a significant personal investment in to one of higher priority or one that requires their unique expertise. This leaves them feeling unsupported and unheard for not being able to see their project through till its conclusion and enjoying the victory lap.
Taking one side of a conflicting pair of proposals between two favored peers based on your own judgement of minimizing risk and maximizing the chance of success over innovation or experimentation with new technologies. The person behind the rejected proposal feels like they didn't get a fair shot or your decision was based on illogical bias towards the other individual.
Reallocating headcount off a leader's team that is just as saturated with work as the others but whose priorities are at lower risk of failing or causing significant harm to the business' bottom line. The impacted leader feels like they are being unjustifiably punished or put at a disadvantage compared to their peers when being held accountable for their delivery.
Overriding someone's architectural decision that provides significant improvements to key value metrics but significantly deviates from organizational standards and introduces risks to toil management and overall supportability. Those involved in the forward-looking design see their research and hard work into the new design thrown away and feel like their contributions are not valued.

These examples are general enough where you might find similarities with what you've experienced. They all represent decisions made with the best of intentions but deliberately required a sacrifice of goodwill or interpersonal currency.

Key Considerations

There are a few considerations I weigh when facing these scenarios:

What would a "good" leader do when presented with this as an option? Would they ever consider this an option at all? I say absolutely, yes. The ability to identify the right places to apply this tradeoff while never irreversibly damaging a relationship is what separates the good leaders from the great leaders. They build bonds that can withstand the strikes of single decisions. The great leaders construct visions that those around them are rallied around, above individual decisions that may or may not favor them.
When considering "people", it is not a singular construct in reality. Leaders spend considerable amounts of time and effort managing the fact that they typically work with people with potentially conflicting assignments, motivations, priorities, ideals, and personal values. It would be reductive to consider human debt from a singular perspective when in some cases the primary, "noble" objective is one directly at odds with one or more of these "people."
Is Human Debt inevitable? Is the decision to sacrifice a part of a professional relationship something every leader will have to face given enough time and experience? Again I say, absolutely, yes. With enough time and experience, great leaders hit these scenarios enough times, fail, and pick themselves up again the next time to understand the balanced formula for success. Eventually, they find the healthy equilibrium.
Can Human Debt be paid off? Humans are not deterministic, transactional things like codebases or software systems. Resolving the consequences of a decision that antagonized someone might be minor enough to do, or significant enough to be considered irrevocable. Some burned bridges are just impossible to rebuild. Great leaders apply these decisions deliberately with full understanding of the greater effect of their actions.

Conclusions

As leaders of people, our problems don't always have perfect solutions. People are not deterministic like code, and even with software you're always balancing tradeoffs in the moment and between the short and long term. If we spent all our time just nourishing our professional relationships, we'd come to be known as the friendly boss that gets nothing done. If we took every opportunity to push everyone away, well we'd probably just be known as the resident jerk...who got nothing done.

We all have to accumulate some amount of human debt, the spending of the goodwill we work hard to build and nurture in our professional relationships. It is the legal tender in the marketplace of solving hard problems. The greatest leaders are the ones that understand how to balance the savings and spending of this currency. Just remember to be frugal with your spending and know that a strong habit of building savings has always been sound advice.

The post was authored with editorial support (Claude Opus 4.5) and image generation (Nano Banana 3 Pro) from Generative AI. All words are my own.

A Practical Introduction to Generative AI Terminology

2026-06-14T00:00:00Z

AI buzzwords are everywhere. Terms are thrown around in dialogue that feel like they've existed for decades but have only emerged in the past year or two. I've experienced a broad disparity between two groups of people: those I would consider "AI power users," regularly on the bleeding edge of every new innovation, and those who have only dabbled in the subject and wouldn't be able to grasp whatever "agentic" thing everyone is raving about. I do my best to be aware of the wave of AI hype and keep myself informed of all the lingo. If you're feeling like you're behind, or have no idea what "an agentic workflow integrating with an MCP server using the latest model from Anthropic with the larger context window" is, read on.

I'd like to provide short explainers of a few terms related to the GenAI tools that have sprung up within just the last 12 months. I will approach this from first principles, so that anyone feeling behind on the discourse can quickly catch up. We will cover the following terms: LLM, Hallucination, Context Window, System Prompt, Agent, MCP, Tool, and Skill.

A lot of what is presented as fact or best-practice was accurate as far as I know at the time of writing. These statements might get stale within a year or a month, it's truly hard to say with the pace of change.

Large Language Model

Large Language Models or LLMs are the foundation of the latest wave of AI hype and the core of what powers most of the modern AI technology mentioned below. You can read up on the theory and science behind LLMs as well as the years of research that went into taking them from concept to product. There are even some who argue that LLMs are fundamentally the wrong path to take humanity into a new golden age of AI and technology. At their core, they are computationally massive systems trained to predict what comes next given an input, specifically, what token (a unit of text, roughly a word or word fragment) follows said input. That basic premise, scaled up with massive computational power and training data sourced from the internet, manifests in higher-level abstractions like the chat interfaces you've likely already used.

Models like ChatGPT, Claude, and Gemini are typically referenced as "frontier models" and stand at the cutting edge of generative AI capabilities. There are dozens of other models available, spanning various specializations and scales, with some being fully open source.

Hallucination

One of the most important characteristics of LLMs to understand, one that shapes all the techniques built on top of them, is that they are fundamentally non-deterministic. Said another way, they're probabilistic, meaning if you provide the same input twice given exactly the same context, there is no guarantee the output will be the same. You know that disclaimer tucked into basically every LLM chat tool you might use? "Insert LLM name here can make mistakes." This disclaimer warns of hallucination, which refers to a model generating confident but factually incorrect or fabricated information. This stems from the model's probabilistic nature. It has no inherent ability to understand its inputs or access ground truth about the world. If you'd like a demonstration, just try asking a model like Claude Sonnet 4.6 how many R's are in the word strawberry.

Context Window

LLMs have what is called a context window, which is a measure, in tokens, of how much text the model can consider at once when generating a response. Modern LLMs commonly have context windows of hundreds of thousands of tokens up to millions.

One might assume that a model with a 1 million token context window would deliver consistent output quality all the way up to that limit. However, modern LLMs suffer from what's colloquially known as context rot. Once a model's context window reaches around 80% of its limit, the model's output quality takes a significant drop. Because LLMs are functionally probabilistic "next word" guessers, every time a new input gets sent in, it is really just appended to the end of the ongoing session and that entire session is then sent back into the model for the following output to be generated.

When operating over the course of an extended session with an LLM, it's recommended to periodically either start a fresh session when the utilized context window is approaching around 80%, or perform what is known as compacting the session. This basically feeds the entire session history back into a fresh session with the model to be summarized and used as a more token-efficient representation of the context built up in the session up to that point.

System Prompt

Products built on LLMs will typically use what's called a System Prompt, which is a set of instructions automatically inserted before your input, giving the model guiding principles and constraints to follow when generating responses. You can browse Anthropic's published system prompts for Claude for a real-world example.

Agent

The simplest implementation of an LLM is one of basic text input and output. This was the first iteration of ChatGPT that was released and provides more-or-less a direct experience of what LLMs provide as a technology. Prompt in, generated content out.

Agents distinguish themselves from basic LLM interactions in two key ways: First, they can execute multiple steps before producing a final output, including follow-up clarification and iterative planning. Second, they can interface with external systems via APIs, Tools, and MCP servers (explained below), allowing them to act on the world rather than just respond to it. Because of this inherent flexibility and underlying power of LLMs, all varieties of Agents have sprung up from those that can code autonomously all the way to ones that can provide automated customer service over the phone.

Model Context Protocol (MCP)

The Model Context Protocol or MCP was created by Anthropic, the creators of the Claude series of frontier models, and provides an open source specification by which LLMs can integrate with external systems. Much like REST provides a standard by which systems can publish an HTTP-based API for applications to consume, MCP provides a specification by which servers can expose an interface tailored for LLM clients.

Though competing specifications like Agent-2-Agent exist, and despite significant scrutiny from multiple cybersecurity researchers, MCP remains a widely adopted specification with broad product support.

Tool

A Tool is how an Agent interacts outside of its own process boundary. It is a discrete, callable function that an Agent can invoke to interact with something outside its own context like reading a file, querying an API, or running a terminal command. For example, a minimal description of what a "Coding Agent" is can be summarized into 3 parts: 1. an LLM that provides the engine of the agent, 2. a set of tools that can read files, create files, and edit files, and 3. a system prompt that describes to the LLM its purpose and scope as a coding agent.

Unlike MCP, which is a broad and general protocol, individual Tools are narrowly scoped to a specific capability: a single API endpoint, a file operation, or a shell command. This has advantages such as allowing certain models to be more selective about which tools they pull into their working context for a given task. Tools can also provide a more robust security context within which a model is given permissions to operate and thereby reduce the risk of unwanted actions being executed.

Skill

Skills are an open specification from Anthropic that encode specific agent capabilities in a Markdown file, augmenting what an Agent can do beyond its default behavior. Skills allow for repeatable tasks to be defined and quickly invoked. Typically, a Skill describes a particular task, the Tools and integrations needed to accomplish it, how to use those integrations, and the step-by-step process to complete it.

One of my favorite skills is also one of the simplest: /grill-me. The Skill's author, Matt Pocock, describes it best in its opening lines, which also happen to make up about 3/4 of its total content:

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

I have found these concepts cover enough of the fundamentals to navigate the discussion and innovation swirling around Generative AI. I hope you find them useful. If so, please consider passing it along to someone who's been quietly wondering what all the noise is about.

The post was authored with editorial support (Claude Sonnet 4.6) and image generation (Gemini 3.1 Pro) from Generative AI. All words are my own.

Sanjay Nair's Blog

The Personal Project to Win Your Next Career Fair

Two words: Personal Website

1. Build the Website and Show off the Code!

2. Create an Automated CI Pipeline

3. Deploy Your Website to a Public PaaS

Getting to Know Terraform

Getting My Feet Wet

Getting My Hands Dirty

Moving the Needle Forward

Asynchronous JavaScript

Callbacks

Promises

Async/Await

Final Thoughts

Further Reading

What is CICD — Concepts in Continuous Integration and Deployment

CI : Continuous Integration

CD : Continuous Deployment

Examples of CICD in Real Projects

ReactJS

Homebrew

TensorFlow

Next Steps

Tools:

Convoluted Convolution

How this would go in software

Metastability — how physics beat us

Our Project Results

Conclusions

How to Make a Q&A Chatbot With Machine Learning

Some Setup

Time to Code

Basic bot setup

Adding some machine learning

Taking it for a spin

Conclusion

Other resources

The Wide World of Databases

Relational Databases

Document Databases

Key Value Stores

Column-Oriented Databases

Graph Databases

Misc

Conclusion

The Wide World of Software Testing

Unit Testing

Integration Testing

End to End Testing

Performance Testing

Load Testing

User Acceptance Testing

A Light Introduction to AI Safety

A (Very) Brief History of AI

The Possibility of Artificial General Intelligence

The Fast Track to Superintelligence

The Need for AI Safety

What Can be Done?

Conclusions

A Light Introduction to Cloud Services

Compute — Virtual Machines

Object Storage

Databases

Application Platforms as a Service

Serverless Platforms

Streaming and Data Processing

AI and Machine Learning

Configuration and Administration

Getting Started With Open Source

Step 1: Go to the Source (Code)

Step 2: Find Something to Contribute To

Step 3: Do Your Homework!

Step 4: Fork and Code

Step 5: Open a Pull Request

How to Open Source Your Code

Step 0: Identify the Opportunity

Step 1: Prep the Code

Step 2: README

Step 3: The License