One topic that can be convoluted is project setup. I expected to find a simple command-line utility like python init, something I could quickly use to spin up a project structure. There are some utilities that do this job for you, such as Poetry and UV.

However, for the sake of understanding, I really wanted to work with the basic tooling available: more hands-on work with pip and virtual environments, and craft my setup from there. Setting up a basic project with these tools, however, can involve a lot of tedious steps.

The aforementioned book does a great job of detailing how and what to set up as you create basic to sophisticated projects. There’s also plenty of material on the internet that describes different project setups and approaches.

So, I decided to automate the process and share what I have so far…

The Python Project Initializer Script

Here’s the link to a repo that contains the script I created:
init_python_project.sh.

This script automates the creation of a very simple Python project with a virtual environment, a few tools for linting, formatting, and testing, and a program entry point.

Script Breakdown:

This script automates the setup of a basic Python project, providing everything you need to get started quickly and efficiently. Here’s a breakdown of what it’s doing:

1. Create the Project Directory

The script begins by asking for a project name and creating a directory with that name. This directory serves as the root of your new project.

if ! mkdir "$PROJECT_NAME"; then
    echo "Error: Failed to create project directory."
    exit 1
fi
cd "$PROJECT_NAME" || exit

This ensures that the project directory is created successfully, and the script exits gracefully if an error occurs.

2. Set Up a Virtual Environment

A virtual environment isolates dependencies for your project, preventing conflicts with system-wide Python packages or other projects.

"$PYTHON_VERSION" -m venv .venv

source .venv/bin/activate

• Virtual Environment Creation: python3 -m venv .venv sets up an isolated environment within a .venv/ directory. When using vscode with python tools, opening the project directory will automatically pickup the virtual environment.

• Activation: Activating the environment ensures all dependencies installed via pip are scoped to this project.

3. Initialize Dependencies

The script installs a few handy tools for development:

• Black: A code formatter that enforces a consistent style.

• Flake8: A linting tool for catching style and syntax issues.

• pytest: The most common Python testing framework.

pip install --upgrade pip
pip install black flake8 pytest

This ensures that your project starts with tools for formatting, linting, and testing.

4. Create a pyproject.toml File

The script generates a pyproject.toml file, a standardized way to configure Python tools and projects. This file simplifies configuration and avoids cluttering the project with multiple tool-specific files.

Example contents for pyproject.toml:

[tool.black]
line-length = 88
target-version = ['py38']

[tool.flake8]
max-line-length = 88
exclude = [".venv", "venv", "tests/"]

• [tool.black]: Configures Black to format code with a line length of 88 characters, targeting Python 3.8.

• [tool.flake8]: Configures Flake8 to match the same line length and exclude directories like venv and tests.

By centralizing configurations in pyproject.toml, you maintain a clean and modern setup.

5. Generate a requirements.txt File

To help with reproducibility, the script uses pip freeze to list installed dependencies and lock them into a requirements.txt file.

pip freeze > requirements.txt

This makes it easy for others (or future you) to recreate the same environment using:

pip install -r requirements.txt

6. Create Basic Project Files and Structure

The script scaffolds a simple, functional Python project structure. The resulting directory looks like this:

<project-name>/
├── .git/
├── .gitignore
├── .venv/
├── LICENSE.md
├── pyproject.toml
├── README.md
├── requirements.txt
├── <project-name>.py           # root level entry point
├── <project-name>/
│   ├── __init__.py
│   └── __main__.py             # Entry point for the application
└── tests/                      # Tests directory
    ├── __init__.py
    └── test_placeholder.py     # Placeholder test file

This structure provides a clean starting point for a simple project.

7. Set Up Git

The script also initializes a Git repository and sets up a .gitignore file for version control.

How to Use the Script

You can clone or simply download the script file. Then make it executable and run it with the filename like so:

chmod +x ./init_python_project.sh 

./init_python_project.sh

This will create a project in the same directory as the script.

Make the Script Available Anywhere

What I do is add the script in a location where my PATH variable will pick it up. I’m running a Mac with Zsh as my shell. Here’s how you can do it:

1. Move the Script to a Directory in Your PATH
   A common location for user scripts is ~/bin or /usr/local/bin. you can move the script into that directory.

mv init_python_project.sh ~/bin/

2. Add the Directory to Your PATH
   If ~/bin isn’t already in your PATH, add it in your ZSH configuration file (~/.zshrc):

# look for a line like this, it may be commented-out
export PATH="$HOME/bin:$PATH"

Then reload your ZSH configuration:

source ~/.zshrc

3. Call the Script from Anywhere
   Now you can use the script from any directory:

init_python_project.sh

This makes it convenient to spin up a new Python project in any directory.

Why Automate?

By automating all of these steps, this script allowed me to learn a lot about Python’s tooling and ecosystem while saving the time and hassle of manually setting up each new project.

It’s a great foundation for small projects and can easily be extended as my needs grow.

Grab the script here and let me know how it works for you! Feel free to add issues, submit pull requests for improvements, or fork the repo for your own needs.

Automated tests are wonderful. They can give you confidence that the code you write works. They can document the behavior of your application. And they can also help prevent regressions introduced when you update your applications.

However, sometimes a bug can slip into your tests and cause them to lie to you! You see a test pass, and without carefully checking, you can get a false sense of confidence, making you think that your code works when really, you’ve allowed a bug through.

A coworker and I discovered this recently while reviewing one of their tests. Let’s explore an example…

TL;DR

When using Testing Library’s waitFor function to test asynchronous code, remember that it returns a Promise. So make sure to use await or .then.

Do this:

it('tests some asynchronous code', async () => {
  // arrange
  // act

  await waitFor(() => {
    //assert
  });
});

Or this:

it('tests some asynchronous code', () => {
  // arrange

  waitFor(() => {
    // act
  }).then(() => {
    // assert
  });
});

But NOT this:

it('tests some asynchronous code', () => {
  // arrange
  // act

  waitFor(() => {
    // You'll think that you asserted, but you probably didn't.
  });
});

They mention this in the docs too…

The Example

I created a small demo application for illustration. Here’s the link to the repo.

This little React application takes some input text, reverses it, and then displays the reversed text to the user.

The reversal of the text is delayed by 200 ms. In the real application where we encountered this type of bug, the action that my coworker implemented invoked an API call. The application had to wait for this API call to finish to display the results. This example is contrived to mimic that behavior.

// This reversed result is delayed and returns a promise. This is to 
// mimic the behavior we might encounter in an API call, such as with
//.fetch.
function delayedReverseString(theString: string): Promise<string> {
  return new Promise((resolve) => {
    setTimeout(() => {
      const reversedString = reverseString(theString);
      resolve(reversedString);
    }, 250);
  });
}

Before we try it out, let’s examine the test…

  it('reverses entered text and displays reversed text to user', () => {
    // arrange
    render(<App />);
    const input = screen.getByPlaceholderText('Enter text...');
    const reverseButton = screen.getByText('Reverse!');

    // act
    fireEvent.change(input, { target: { value: 'hello' } });
    fireEvent.click(reverseButton);

    // assert
    expect(screen.getByText('olleh')).toBeInTheDocument();
  });

As you can see, our test:

1. Renders the application.

2. Gets the input element and the reverse button.

3. Enters the text “hello”, and clicks the button, just like a user would.

4. Asserts that the reversed text is displayed in the document.

When we run the test, we can see it fails…

Since we know the result is delayed, we’ll need to modify our test to wait for that result to display. So let’s use Testing Library’s waitFor function to do that!1

...

// assert
waitFor(() => {
  expect(screen.getByText('olleh')).toBeInTheDocument();
});

...

After that modification, the test passes!

Awesome. Our test is passing. However, when we try out the application, something seems off…

After entering some text and clicking “Reverse!” It just shows the text we entered! It’s not magically reversed!

So what mistake did we make in our test?

Let’s add some logging statements to follow along with the execution of our test.

// assert
console.log("before waitFor");
waitFor(() => {
  console.log("before assertion");
  expect(screen.getByText('olleh')).toBeInTheDocument();
  console.log("after assertion");
});
console.log("after waitFor");

Notice that we never see “after assertion“. This is because our expect statement is failing and throwing an error. It will never hit the line after our assertion.

We can prove this by adding a try-catch block.

// assert
console.log("before waitFor");
waitFor(() => {
  console.log("before assertion");
  try {
    expect(screen.getByText('olleh')).toBeInTheDocument();
  } catch (e) {
    console.log("EXPECT FAILURE:", e);
  }
  console.log("after assertion");
});
console.log("after waitFor");

We can see that an error is thrown, but our test continues on its merry way, reporting success.

Why doesn’t our test fail?

Because waitFor returns a Promise.

The problem with our test is that we are not awaiting the returned promise to resolve before moving on. our test block doesn’t detect the error being thrown because in this case, waitFor is effectively swallowing the error thrown by our expect statement.

Let’s see what happens when we introduce async and await.

it('reverses entered text and displays reversed text to user', async () => {
  // arrange
  render(<App />);
  const input = screen.getByPlaceholderText('Enter text...');
  const reverseButton = screen.getByText('Reverse!');

  // act
  fireEvent.change(input, { target: { value: 'hello' } }); 
  fireEvent.click(reverseButton);

  // assert
  console.log("before waitFor");
  await waitFor(() => {
    console.log("before assertion");
    expect(screen.getByText('olleh')).toBeInTheDocument();
    console.log("after assertion");
  });
  console.log("after waitFor");
});

We finally have a failing test! Notice that “before assertion” gets logged about 21 times, and then reports a failure.

This is how waitFor works. By default, it will run the callback once, then it repeats the passed callback every 50 milliseconds for 1000 milliseconds (1 second), or until the callback completes successfully, and resolves the promise. Once waitFor has timed out, it will reject the promise, and pass along the error that occurred. This unhandled error will then cause our test to fail.

Now that we have a valid test, let’s fix our code.

Let’s take a look at the reverseString function.

function reverseString(theString: string): string {
  return theString.split('').join('');
}

We forgot to reverse the string! Thankfully, that’s an easy fix.

function reverseString(theString: string): string {
  return theString.split('').reverse().join('');
}

We can see that our test passes.

And, our application is behaving as expected.

Conclusion

Automated testing is a critical aspect of software development. Good tests can provide confidence that the code we ship behaves as intended. They can help us ensure that it continues to do so by guarding against regressions.

However, it's important to recognize that our tests can inadvertently mislead if not crafted well. It’s possible to create flaky, unreliable tests if we don’t understand our tools well.

Through an exploration of asynchronous testing using Testing Library's waitFor function, we've uncovered a possible pitfall: the failure to await the returned Promise, leading to undetected errors and false positives in test results.

By ensuring proper utilization of waitFor—either through async/await or .then syntax—we can accurately capture asynchronous behavior and detect errors effectively. We can have true confidence in our tests and our code.

Along the way, James shares what he’s learned about embracing new challenges, cultivating a beginner’s mindset, and taking the calculated risks required to make a career transition.

James is currently a Data Analyst at Ramsey Solutions.

Share

We talk about work, what’s going on, how it’s going. We also talk about life. It’s an opportunity to build trust and get to know each other a bit outside the context of work.

One-on-ones are a great way to build trust, get help, and exercise accountability. But sometimes, getting through them can be a struggle.

I’ve been in one-on-ones that can meander. They can be awkward. They can be dominated by small talk. Or have no personal touch at all. Or they are dominated by one side, creating a monologue instead of a dialogue. And at the end of it, sometimes you can wonder what was accomplished.

How do you fix this?

The best place to start is simple…. make a plan. Have an agenda.

In Trillion Dollar Coach, the authors describe Bill Campbell’s approach to 1:1s, summarized as “5 Words on a Whiteboard.” If you happen to snag a copy of the book, you can read about it from pages 46-50.

The template is pretty straightforward. Each party prepares five topics to discuss. If you have a whiteboard available, each participant writes their five topics. Then, they can merge them into a structured agenda.

In the case of a manager-employee (or mentor-mentee as the case may be) meeting, the employee should list their topics first. There are a few benefits to this:

• This type of 1:1 should primarily be for the benefit of the employee. Their topics take precedence. Not a simple status report for the manager.

• This allows the opportunity for the manager to gain some insight into what is on the employee’s mind. What are they thinking about? How do they prioritize? This can be seized upon as a coaching moment in itself.

• Some managers can steamroll the interaction without giving the employee a chance to address topics they need help with or that otherwise need attention.

• If the manager goes first, this can put the employee in the position to mindlessly agree with the priorities as set by the boss and robs them of the chance for them to apply some critical thinking, and share what they think should be prioritized.

It doesn’t have to be five topics exactly. The point is to have some structure and put in some preparation.

Come in with just one topic. Even that would be an improvement.

Exercise just a little forethought and I think you’ll find the next 1:1 you’re in will go much more smoothly.

You’ll get something out of it.

And you might even enjoy it just a bit.

Title:

Update this really awesome API with a new field for a really cool feature.

Description:

Add the field “email” to really-awesome-api-service, so that we can expose it for editing to the user.

Technical notes:

1. Add the new field to the Data Object

2. You might need to update the database

3. Update the controller to support CRUD operations on the new field

4. Write test cases

I’ve seen much less detailed tickets. In fact, this one was pretty good in my experience.

So what’s the problem? What kept me from just doing the thing?

I didn’t know how to do it.

I went to the GitHub link for the source code. I perused it for a bit and realized it was a Kotlin service.

I don’t know how to program in Kotlin.

I knew almost nothing about this application, including the tech stack it was built on.

Spring? Maven? Hibernate?

I have barely touched any of them.

Not only that, I had no idea what database needed to be updated. Or, as the ticket hinted at, if it even needed to be updated.

There’s a lot I didn’t know.

So, I wrung my hands, gave up, and cried in the corner, while rocking in the fetal position.

Just kidding…

As engineers, this is exactly what we’re paid to do. Encounter something we don’t understand or know. And figure it out.

So here’s how I figured it out.

First, I started with what I did know:

• I knew this was a REST API, with a database behind it for persistence. While I haven’t worked in this kind of tech stack before, I know the concepts from studying and working in similar applications.

• The ticket mentioned a Data Object. I know that’s a pretty common pattern for ORMs (Object Relational Mappers). It would make sense that I would have to find and edit this part of the code.

• I knew that Spring uses the MVC pattern for web APIs. I understand how that pattern works, so it gives me a frame of reference as I navigate the code.

• I’ve worked in .NET, Ruby on Rails, and a handful of other frameworks implementing essentially the same thing. At the end of the day, it involves making migrations for the database to the new schema, updating the models and entities that talk to that database, then updating the controller to provide the methods to view and edit that information. There might be some nuance, and some middleware to take into account, but those are the bones of this kind of task.

So I had a rough idea of the big picture subtasks, but what I didn’t know was…

• How do I make the migration to add the new field (changes to the underlying database schema)?

• Are these migrations stored in scripts anywhere?

• Is there a special command I need to run to do those scripts? or sequence of commands?

• What database is this connected to?

• Do I need to directly connect to this DB and make any changes there, or can it be done completely from the application code?

• Are there any other tables or relationships that need to be accounted for? Any dependencies I could break in the process?

• How do I even set up and run this project?

So how did I begin to answer these questions?

First, I searched through the code for anything related to the data object. I found the relevant code, and lo and behold, it had some fields I recognized. It seemed simple enough to copy the code from one field and modify it to suit my needs.

Then, I searched for an example field name throughout the entire project. For our purposes, let’s say I used the field “FirstName” to base my work on. I found all references to “FirstName,” and this painted a picture for me of all of the bits of code I’d have to amend for my new use case.

Now, I had to figure out what database the app connected to. I knew from experience that this is usually defined in some kind of configuration file, and was able to find that.

Next, I looked through the project’s README to see if there were any instructions on setting up the project. There were, so I proceeded to get the app up and running on my machine.

Now, I had what I thought was all of the relevant code updated, and I had the project set up. However, I still couldn’t figure out how to migrate the data to the new schema. This is when I resorted to reaching out for help.

I looked through the project's commit history and found the person who most recently did work there. I shot a message to that person.

I couldn’t get any further, so I took a two-hour break and scrolled through Instagram until he could respond.

I’m just kidding again.

I didn’t want to let that block me, so I kept digging and trying to think of how I could get this information.

Then it hit me…

This seems like a pretty typical task that’s probably been done before… There’s probably an old pull request similar to the work I’m doing now. So I searched all of the closed PRs for the text “add field.” And sure enough, several results popped up.

I found a good example and it highlighted to me a few things I did right, and some things I had overlooked.

I still didn’t have everything I needed though. I still needed help. So I amended my questions to my coworker with the new information I had. I was able to ask more detailed, explicit questions, and he was able to give me much more direct, simple, and higher-quality answers with this new information.

We weren’t ready to activate on the work yet. So, I updated the ticket with a summary of what I had learned. That way, the next engineer to take on the work would start from a much better position.

As I reflected on my day, I realized something. I do this all the time.

There’s a pattern here.

The following is my best attempt to abstract what I did into a step-by-step process:

1. Start with what you know.

2. Identify what you don’t know.

3. Craft the right questions to ask to learn what you don’t know.

4. Figure out an order that makes sense to ask those questions in. Some answers to questions are dependent on answers to previous questions. There may be an inherent order to work in.

5. Ask those questions via whatever methods are available…

   • Read through the source code.

   • Read through the documentation.

   • Review language and tooling documentation.

   • Search Google.

   • Ask ChatGPT 😜.

   • Ask a human being.

   • Get direct help by pairing with a person.

6. Repeat the process, refining the details until you have clear action steps to take that get you closer to solving your problem.

7. Solve problems one by one. As you solve, new unknowns will likely reveal themselves. Apply the same process to figure these new problems out.

Fundamentally, this is the essence of what I have done as an engineer for my entire career. Repeating this process and variations of it as I learned more and encountered new, more challenging problems.

As you advance in your engineering career, the problems you tackle will be less well-defined, more ambiguous, and more challenging across several dimensions.

But the fundamental process of problem-solving remains the same. If you master that process and build those problem-solving muscles, you’ll unlock the ability to tackle more interesting, difficult problems.

And you’ll get to experience the rewards that come with solving them.

Have fun.

On New Year’s day, four other men and I set off on a backpacking trip to hike a section of the Appalachian Trail. We started from Woody Gap, near Helen, Georgia, and eventually ended the trip by getting picked up on Highway 75, just past Blue Mountain Shelter.

We hiked about 32 miles over the course of three days.

By the end of the trip, we were all hurting, and soaking wet. We were basically hiking in a cloud for the last two days. I can still feel the cold, floating water particles brushing against my skin.

And that was in the interludes between actual rain.

Towards the end of day two, it was getting dark fast. One of my hiking buddies and I were trailing behind the others, and we still had well over a mile to go by the time night had settled in. We ended up hiking in the dark for almost an hour.

Yep, it was only an hour. BUT, this was my first time doing any kind of night hiking. My headlamp was dim. And as though all that wasn’t bad enough, we were still in thick fog. So both the light from my lamp and my friend’s headlamp was being dispersed and reflected in all directions. We maybe had at best a couple of feet of visibility on the ground in front of us.

Cold, wet, and not exactly sure exactly how far the shelter was, we had been hiking almost 14 miles for the day, and my feet and legs were blistered and beat.

We were less seeing our way down the trail, and more feeling our way.

And at that moment, we weren’t exactly sure how long we’d be out there.

As I’ve been reflecting on this experience, I’ve realized something…

The way I felt stumbling and feeling my way through that trail for an hour, only seeing a foot or two in front of me, is the same way I’ve felt at work over the last few months.

Why?

We’ve been in a season of product discovery.

And it’s messy.

For much of my career, I’ve had more-or-less well defined problems AND solutions put in front of me to work on.

“Program X, so that we can do Y.”

Or…

“Help build this widget, so that we can make money.”

That’s a slightly tongue-in-cheek description. But still, I think a fairly accurate summary of most software engineering assignments.

This time, however, my team has been given a customer problem. No solution prescribed. We get to come up with that part.

And just like that hour in the dark on the trail, it’s been messy, very touch-and-go, a little anxiety-inducing.

And also, just like that experience on the trail, it’s pretty dang cool.

We’re in a problem space where we have extremely limited visibility. So we’re relying on a lot of qualitative feedback to get signals that we’re going in the right direction. We know where we need to go. It’s just really hard to see how to get there.

And as we’re going, we’re building more sophisticated tools and solutions to track and gather data, so that we can build more confidence as we go.

It’s kinda’ like building a better headlamp while you’re walking down a dark path.

And thankfully, we haven’t had to build our own trail to get to our destination. Others have gone before us. We’ve been relying heavily on Teresa Torres’ Continuous Discovery Habits to give us tools and language to stay on course. It’s a definite must-read if you’re building digital products.

My friend and I kept going. One step in front of the other. And finally, we heard our friends calling to us. And we eventually saw light from the campsite in the distance.

We made it.

All we had to do was keep going.

And at work, through all of the uncertainty that’s come with working on this problem, we’ve identified and are beginning to deliver a solution that will take a step towards tackling it and providing value for our customers.

Now off to find the next solution.

In a group discussion at work a few days ago, one of my teammates asked the question, “how do you deal with burnout?”

I’ve been thinking about this question a lot lately. I feel like I’ve been approaching burnout myself.

It’s been a very busy summer. With a lot of change for all of us on the team. And a lot going on personally as well.

I think we all experience burnout in some shape or form that’s unique to us at one point or another.

Frankly, I haven’t been writing a lot lately because I’ve simply felt too overwhelmed to mess with it. So, I figure what better way to get back into writing than to address this very thing.

Am I Burned Out?

How do I know I’m getting burned out?

I begin to notice a few things just aren’t quite right. It usually looks like some combination of the following, in no particular order:

• I’m more irritable. Things that I might normally let go just irritate me more.

• I feel tight, and tense constantly. I especially feel this in my back, shoulders, and hands.

• My sleep quality is trash. Even when I can sleep, it seems shallow, less deep. I tend to wake up two or three times in the night.

• I wake up thinking about upcoming meetings or conversations.

• When I get home, I just feel thoroughly exhausted. I would rather just go to bed than do… anything.

• Activities that I enjoy just seem like a chore. I have no intrinsic motivation.

• I feel emotionally numb most of the time, with random outbursts of emotion. Crazy stuff like crying at a commercial with a puppy or something inane like that.

• Instead of using leisure time working on productive things (e.g. this newsletter) I struggle to bring myself to do anything more than drink beer and watch Netflix. And no, that’s not bad once in a while. But there is a limit…

• I struggle to focus and make decisions.

• Loss of connection to the sense of meaning in my work or other pursuits.

I’ve been experiencing all of these to some degree or another over the last few months.

Certainly, there has been a lot going on that is out of my control. But there are some things that I am in control of that I haven’t been perfectly consistent on or disciplined about.

The Disciplines

There are a few cornerstone habits, or disciplines, in my life that I know if I am inconsistent with, everything else is thrown off.

These disciplines are:

• Exercise

• Eating well

• Sleeping well

• Spiritual connection

I’m sure if you’ve read any other article on this topic, this list isn’t a surprise.

Just open up another tab, right now, and search “burnout.” I guarantee the top results will talk about sleep, exercise, diet, and probably something related to the spiritual, or social connection at a minimum.

But the fact is, when I’m feeling burned out and I do a little reflection, I don’t have to go too far back to notice that I haven’t been consistent with maintaining one of these disciplines. Or all of them.

So for me, the key to managing stress and staving off the onset of burnout is maintaining these habits. And reestablishing them when they get out of wack.

It comes down to fundamentals.

Exercise

Exercise releases a lot of feel-good chemicals.1

Many of us have been there. In the middle of a workout, it seems like torture. But afterward, we feel amazing!

I like to do this after work. When I’ve had a hard day, I have to get out of my mind and into my body.

There’s nothing like a hard workout to help me do that.

It helps me release all of the tension that has built up from a desk job. And that workout creates a boundary that forces me to separate work time from personal time.

Aside from that, it gives me the strength to do the activities I enjoy. And just being able to walk up the stairs without losing my breath gives me confidence.

The problem is that I might start the week off great. I work out for an hour Monday evening.

Then, by the time Tuesday comes around, or whatever the next day is in my training schedule, It seems impossible just to get my sneakers on.

Eating Well

When I eat like trash, I feel like trash.

When I’m stressed out, I tend to gravitate towards fried food, sweats, and more beer.

When I go to lunch and I have the choice between the salad or a chicken parmesan sub… I’m probably going for the sub. It just feels better…

… for about an hour.

Then I’m bloated and want to take a nap for the rest of the afternoon.

And forget working out when I get home.

Sleeping Well

This is the most challenging one for me.

It’s very difficult to maintain a consistent bedtime, and usually, that translates to sleeping later, which throws my whole morning routine off, and then I get to work already feeling behind and stressed.

This is probably the one discipline that If I could fix and be consistent with, it would change all the rest.

Spiritual Connection

For me, this looks like studying and praying every morning. And meditating (often through journaling). Keeping a daily connection with God.

I need the help.

Even if you’re not religious, you may recognize the value in some sort of practice that puts you in a position to think about your life. To reflect and evaluate.

All of these disciplines are interconnected.

If I’m sleeping well, I can get up in time to study, pray and journal.

When I’ve studied, prayed, and journaled, I’ve had space to think, process whatever is going on, and look at things from a bigger perspective. Even with some gratitude.

Once that’s in place, I’m much calmer throughout the day. More present. I’m thinking about my actions, my words. I’m responding instead of reacting.

Since I’ve shown up from that more calm, peaceful, present place, I have less to be anxious or worry about. So I sleep better.

That gives me the energy to exercise at the end of the day. When I exercise, I crave water and healthier food. It’s just that much easier to eat well. Because I’ve eaten well, my mood and emotions are better regulated. Which in turn helps how kind, present and sharp I can be throughout the day.

Which helps me sleep.

And on, and on…

These disciplines form a framework around which the other parts of my life hang. And when any or all of them falter, the whole thing gets out of wack.

No Silver Bullet

None of these disciplines is a silver bullet.

Going for a run will not take away the need for that hard conversation you keep putting off.

They don’t automatically take away the stressful environment you’re in, or the tasks that you have to keep up with.

But, again these practices form a foundation from which you can be well equipped to handle and cope with your everyday stressors. And perhaps even find creative solutions to your problems.

What’s Stopping Us?

So I just told you that if you’re at the edge of burning out, you should sleep more, exercise, eat better, and meditate.

Helpful.

I’m just as much telling myself this.

I know what to do.

We know that none of this is new. The habits needed to cope with stress and burnout seem to be well known.

So if we know these are the things that are good for us, why don’t we just do them?

There is something innate to human nature that resists anything beneficial for us. Anything that doesn’t result in instant gratification. Even when we know that it will be good for us in the long term.

In The War of Art,2 Steven Pressfield talks at length about this. Mostly, within the context of creative work. But it applies all the same to any worthwhile endeavor.

He personifies it as Resistance. As though it were an entity. Except, this entity has no motive. It’s simply a force of nature. Not too unlike the Law of Entropy.3

So recognizing that there is an innate pull within us to avoid what’s good for us, how can we counteract that pull? How do we establish the disciplines that are necessary to start coping with burnout?

I’ll address that in Part II of this series on dealing with burnout.

But for now…

I’m going to bed.

Also, one of the most overwhelming, stressful, and yes, even maddeningly frustrating things about working in technology is the fact that things never stay the same and there’s always something new to learn.

Your cheese is constantly being moved.1

So how do you manage the constant stream of change? The constant need to learn a new programming language? A new library? A new framework? A new design pattern? A new tool?

How do you keep up without going crazy?

How do you sustainably grow in your craft?

Previously, I’ve written about the fundamentals of the craft, which can help form a foundation for growth. And, I’ve shared one of my favorite techniques to help manage the time needed to learn.

So while I’m at it, here’s another thought:

Just try to get one percent better today than you were yesterday.

That’s it.

This idea is not very original. In fact, A lot has already been written about the “one-percent rule” all over the internet. I don’t want to repeat all of that, so here are a few of my favorite articles on the topic for further reading:

• The 1 Percent Rule: Why a Few People Get Most of the Rewards

• Continuous Improvement: How It Works and How to Master It

• Get 1% Better Every Day: The Kaizen Way to Self-Improvement

What I do want to do is share a few practical ideas for how to implement this rule as a technologist.

But quickly, why one percent?

First, it’s manageable.

Saying you need to learn C++, for example, is a good goal. However, it’s so broad and so overwhelming that it’s almost useless as a target.

But, saying you need to learn C++, then asking yourself, “what’s one tiny thing I can do to get the ball rolling on this today?” is useful. Maybe that one tiny thing is writing “hello world.” Or maybe that’s learning pointer arithmetic. It just depends on where you were yesterday.

Looking at where you were yesterday, and getting just a little bit better on any given topic feels a lot more approachable than tackling everything all at once.

Second, it’s powerful. One of the most impactful quotes I’ve seen on the topic comes from James Clear:

If you get one percent better each day for one year, you'll end up thirty-seven times better by the time you’re done.2

Most of the impact and changes in your life don’t come from any singular, grand moment. They come from the tiny, incremental decisions and actions made day by day.

So with that, let’s consider an example of how this could look…

You’re a software engineer and your company is moving all of its infrastructure to the cloud. AWS (Amazon Web Services), for example. You’ve never worked in a cloud environment before. So everything is new.

Well, in this scenario, I might say to myself, “I’m going to get 1% percent better today by reading an article that provides an overview of all of the major AWS services.”

It’s day two now. Since I read that article yesterday, I now have kind of an idea of what AWS is all about in general. However, I’m still fuzzy on how my code and the work that I routinely do connects to it. But, I do know a guy in systems engineering, let’s call him “Bob,” that knows a lot about this stuff.

I say to myself, “Self, today I am going to get 1% better at my job by having a meeting with Bob and asking him how my team’s code utilizes whatever AWS products are relevant.”

It’s day three now. And now that I have a pretty good grasp on how our team’s code fits within our cloud infrastructure (thanks to that little chat with Bob yesterday), I wonder what else we could be doing with it? People keep talking about serverless computing, and I think we might be able to use this for our next project.

I start googling, and I come across AWS Lambda functions. So today, I decide I’m going to get 1% better at my job by researching Lambdas to determine if this feature fits our use case.

It’s day four. After learning a little bit about Lambdas yesterday, I think it’s worth investing a little more time into it. So today, I’m going to get 1% better at serverless computing by going through a tutorial and setting up a Lambda myself.

I hope you can see the thread here….

• Take inventory of where you are.

• Identify the topics you need to learn about.

• Keep a list of those topics.

• Look up relevant learning resources; books, videos, courses, and people you work with. Have those handy.

• Execute. Find a few minutes in your day to make progress. 10-15 minutes could be all you need! Doing this within the first hour is a great idea!

You could take this and reduce it to a template:

“I’m going to get 1% better today at X by doing/reading/watching Y.”

In the morning, fill that sentence in. Write it in a journal. And mark it off when you did it!

In a few months, you’ll look back at all the things you improved at and feel confident, knowing that you. can. learn. That you can improve. That the big, scary, uncertain things that looked impossible just a few weeks or a few months ago are now completely within your grasp.

All by consistently showing up and doing just a little. tiny. bit.

I think that most of us would agree that growth in our field of endeavor is important. But it may not be so obvious as to how to go about it.

It takes dedicated time and focus. It’s helpful to have a system to make it easier. In this post, I want to share my number one technique for learning and growth.

Several years ago I was in Charlotte, North Carolina staying with friends for an event. The friend I stayed with was the director of the Charlotte office for an HVAC company. He shared that, years ago as a technician, he would often show up to work early and sit in his truck reading technical manuals before starting the next job. He credited this practice with a lot of his success and advancement in the company.

That story stuck with me. So I have incorporated some version of this practice into my professional life.

So how does this look for me? Well, first I’ll describe the ideal version of how this works, the one I strive for, then I’ll share the actual version of how it plays out.

In the ideal version, I show up to work an hour early. That’s every workday. Five days a week. And I use this hour for learning. That could be reading a book, working on a technical course, listening to lectures, reading articles, or working on a project meant to practice a skill.

In the actual version, I occasionally do everything just described. More often, I maybe get there thirty minutes or fifteen minutes before work. Sometimes I’ll just study at home for a bit before heading to work. Sometimes, I have no time at the start of the day, so I might end the day with a little learning time. And sometimes… not at all.

Admittedly, I’m inconsistent.

But, I do this more often than I don’t do it.

James Clear, the author of Atomic Habits, observed that “You do not rise to the level of your goals. You fall to the level of your systems.”1

This practice is my attempt at systematizing learning and growth into a habit. Something I can fall back on and just do, without thinking too much.

There is so much to learn. Everything keeps changing. Especially in any technology-related field. Which is virtually all of them at this point. Keeping up is just table stakes.

I’ve found that this technique, even when practiced imperfectly, has helped me adapt to the ever-changing landscape of my field. I offer it as a suggestion and hope it’s helpful.

So while the ask was pretty straightforward… actually doing it was a different matter.

He got to a point where he was spinning his wheels. So I jumped in to help out. I looked at it for a little while and I was able to figure out what was going on.

He described me as a "wizard.” I had just done the impossible.

At least, in his view.

Of course, I didn’t feel like a wizard. I was just following instinct… following one piece of code to the next through the inheritance hierarchy. With that and a little help from Google for Ruby minutiae, I was able to trace through the program down to the relevant piece that needed updating.

This experience did get me thinking though… why was I able to go into an unfamiliar codebase, in a language and framework that I am by-no-means an expert on, and, in a relatively short amount of time, figure out what was going on?

I can trace back my thought process back to the Computer Science 2 course I took in the Spring of 2012. Object-Oriented Programming in Java.

In that class, I learned many of the fundamentals of OOP. Abstraction, encapsulation, inheritance, polymorphism. I learned how to apply those concepts with interfaces, abstract classes, generics, and more techniques.

All these years later, I’m still applying those lessons in completely different languages and environments.

When I was young, I had to learn the fundamentals of basketball. You can have all the physical ability in the world, but you still have to know the fundamentals.

- Michael Jordan

Over the years of my career, I’ve seen those concepts play out across several different languages. And I’ve seen them expressed in several different design patterns, frameworks, and software architectures. So with that experience, I have further refined my understanding of these fundamental principles.

I’ve seen good examples.

I’ve seen a lot of not-so-good examples.

I’ve learned from all.

My observation at this point in my career is that I have gotten far more mileage out of learning and practicing the fundamentals of my craft than I have ever gotten out of focusing on the new shiny thing. Or even deeply focusing on a particular language or technology.

Now don’t get me wrong, there are seasons when you do need to keep up with the latest and greatest. Things do change. You need to know what’s possible.

And if you’re career is in a specific area… AWS engineering, just as an example, It’s necessary to know all the ins and outs of that particular technology. To dive deep.

My point is that in any craft or field of endeavor, there are a common set of principles that everything else is built on. The fundamentals.

Not taking the time to learn these fundamentals will hold you back.

Taking the time to learn, practice, and master the fundamentals will unlock an ability to adapt to new and unfamiliar situations. You’ll start to see how they apply across a wide variety of contexts.

You’ll see patterns emerge where there was once chaos.

Then, all of a sudden, things will make sense.

What constitutes the fundamentals for your field or specialty may vary. Here’s my attempt at listing what I think are a few good topics to start with as a software engineer:

• Data Structures and Algorithms

  • The basics are not as scary as you might think. Realize, an array is a data structure. Algorithms are often just the techniques by which we can Create, Read, Update and Delete (CRUD) the data within those structures. Almost everything else is built on top of this.

• Object-Oriented Programming

  • Can you describe the difference between an object and a class?

    • I’ve conducted dozens of interviews, and a good number of candidates struggle with this.

  • The Four Pillars of OOP: Abstraction, Encapsulation, Inheritance, Polymorphism.

  • The difference between Composition and Inheritance.

• Web Programming

  • It’s helpful to understand some basics of how the internet actually works.

    • Computer Networking

    • HTTP/HTTPS

  • JavaScript/HTML/CSS

  • Server-Side Programming

    • How is data exchanged between client and server?

    • HTTP methods

    • CRUD

    • APIs, REST

• Databases

  • Can you create a few tables, relate them, and use SQL to query from them or modify them?

If you need resources to help you get started, here are a few I recommend:

• Cracking the Coding Interview

  • While this book is mainly about interviewing, I find a lot of value in its overview of so many topics from computer science and software engineering. If you don’t know where to start, start here.

• Frontend Masters

  • Pay for a month and spend some time on the beginner learning track.

• Networking for Web Developers

  • Just spending a couple of weeks on this free course will help you have better conversations with systems and network engineers.

You might disagree with some items I’ve listed. Or, you may think I failed to list some critical items. I’m fine with that! Please feel free to add items in the comments.

Mastering the fundamentals is far from wasted time.

So if you’re in a season where you’re wondering, how can I grow? What’s holding me back from reaching the next level? Consider going back to basics.

Revisit the fundamentals.

It will pay off BIG TIME.

Since becoming a tech lead, I’ve been trying to figure out how to do my job. What do I do here?

This blog is a product of that effort. To codify and share the results of that learning process.

So with that, I want to discuss the central theme that I have come to orient my work towards as a tech lead. That theme is feasibility.

Why Feasibility?

Why do I orient towards feasibility?

I feel it’s a natural outgrowth of the organizational design of my company. We borrow a lot of ideas from Marty Cagan and Silicon Valley Product Group. So at the lowest level in the product organization of my company, we are organized as cross-functional product squads.

The squad I work on is composed of a product manager, product designer, myself (tech lead), software developers, and a test engineer. The product manager, designer, and tech lead, together form a product trio.1 In the product trio model, the whole team is responsible for a successful product outcome, while each discipline approaches the outcome from their respective domain. The perspective of their discipline.

The product manager is primarily concerned with value and viability, whether or not the product meets the needs of the business and customer.

The designer is primarily concerned with usability. Can the intended user figure out how to use the product?

The tech lead is primarily concerned with feasibility. Can the solution be built?

What is Feasibility?

So what do we mean when we talk about technical feasibility?

Oxford defines feasibility as “the quality of being possible and likely to be achieved.”

Seems straightforward. From that definition, it seems as though I could answer the question to most projects I’m involved in with a yes or no answer pretty quickly, just based on my gut.

However, there’s a little more to it than that. Much is implied in this definition. What makes something possible? How do I know what’s possible and what’s not? What are the constraints that make something likely to be achieved? What are the hidden constraints that haven’t been considered?

Marty Cagan puts it this way, feasibility is about whether engineering can “…build what we need with the time, skills and technology we have [emphasis added].”2

Time.

Skills.

Technology.

Those are the elements that I focus on.

I’ll attempt to address each of these elements in turn. In reality, though, they are entangled together and must be approached holistically. When you choose to optimize for one element, you may be doing so at the expense of another.

Time

Judging from experience, I think a pretty common misconception is that feasibility is the same as an estimation of when the project will be done. Often a stakeholder might ask what the feasibility of a given feature or project is. But what they are really asking is “Hey, how long will this thing take?”

Feasibility and timeline estimation are not the same. Feasibility may incorporate some element of estimation, especially as a factor when comparing options and deciding a direction. However, they are two very different disciplines.

At my current company, we operate according to the Kanban methodology.3 As my friend and Kanban Coach, Tristan Hood has put it, “Kanban seeks to remove the idea of ‘committing to estimated deadlines’ so estimates become less important for setting a deadline and more important for driving collaboration and building just the right amount of thing in the right amount of time.”

So while the timeframe isn’t without importance, it is secondary to providing value. If the thing you’re working on is indeed the next right thing, It should be focused on until completion.

There are times when you have some work that has a fixed delivery date. In this case, the goal of the feasibility analysis is to come up with a plan to hit a target.4 However, it’s more useful to design the work in such a matter that it promotes iteratively discovering and delivering products that provide value, rather than defaulting to fixed-date project commitments.

So for feasibility analysis, my main concern with the time element is determining what the relative size of our implementation options are. Option A might take longer than option B, but it accounts for X, Y, and Z concerns. Option C might be faster than all the other options. However, option C comes with such and such trade-offs to consider. Understanding this informs our decision as a team about which avenue of implementation to venture down.

As we further decompose the work, we may be able to perform some projections. The projections aren’t meant to imply fixed-date commitments, but to inform decision-making along the way.

There’s a lot that can be written on estimation. And has been! I plan to distill what I’ve learned about software estimation into a future post.

Skills

Skill is just the ability to do something. There are several dimensions to consider when determining if your team has the skills to practically execute a project.

Probably the first obvious dimension is technical skill. Does your team have any experience with the tech stack of the project? If the project calls for building an API in Java, and the team members have been working in the .NET stack for the past five years, you’ll have a learning curve that must be factored in.

And I say the team on purpose. To use the previous example, it may be that one of the team members did tons of Java API development at their last job. But if the other team members haven’t, that team member is going to be spending a lot of time training and communicating rather than coding.

Aside from specific technology, there is the craft side of software engineering. Think algorithms, design patterns, data modeling, architecture, requirements analysis. All of the skills that transcend languages and frameworks.

The greater the difference is between the team’s technical expertise and the expertise demanded by the project, the more this becomes a limiting factor.

A closely related dimension to technical skill is experience. Do you have a team of junior developers? A team of more seasoned veterans? Or a mixture? The more robust that the solution for the project is required to be across any given set of quality characteristics5, the more need there is for seasoned engineers to be involved in the design and guide implementation.

A third dimension is domain knowledge. How familiar is the team with the business side of what they are attempting to implement? Do they understand the user’s pain? If you’re tasked with implementing an accounting system, it helps to know the jargon that accountants use. The members of the team have to be able to take the concepts from the domain, abstract them into a model, and then translate that model into instructions that a computer can understand. The more understanding and context that the team has of the application of the system they’re building, the more accurate their implementation will be.

Another dimension to consider too is the team’s experience together. Has the team worked together long enough that they have had time to gel, to get to the point where each member could almost finish each other’s sentences? How’s the sense of trust on the team? The practice of building durable teams has gained popularity in recent years because there are so many advantages of having a team that has a shared history and experience.

There does come a point where the team and the project just aren’t compatible due to a mismatch between the skill-set of the team and the project’s requirements. In this case, you might:

• Scrap the project. Possibly reevaluate later.

• Request work or assistance from another team that is capable.

• Reevaluate and see if there’s another solution to the problem you’re addressing that is practical for the team.

Technology

When it comes to handling the Technology aspect of feasibility, I view it as answering a series of questions…

Within our existing technology stack, do we have something already that can solve this problem?

If we do have something that kinda’ fits the problem, but not quite, what is involved in modifying or extending that system to meet the problem? How difficult would this be?

Do we need to build something entirely new?

Can we buy a solution?

If we can buy something that meets a portion of the need, can we build the other portion to make up the difference?

Whether we build or buy, how does that integrate with the existing system?

Is working on that integration going to be harder than just modifying the existing system(s)?

That’s just a handful of examples I can think of. Answering these questions takes at least a couple of skills. You have to be able to apply some principles of software design and architecture. And you have to take an investigative approach.

Applying software design and architecture involves being able to map a customer or business problem to a possible software solution. And then use knowledge of various methods of software construction to work out a possible design for that solution. Or better yet, several alternative design options.

This is informed by a few things. An understanding of your current system. An understanding of the technology ecosystem that you work in; for example, what similar projects are available in your company to draw examples from? What services or APIs are available? It’s informed by experience; what have you built in the past? And Informed by education; what techniques and design patterns have you formally studied? What’s the latest innovation you’ve read about on TechCrunch or some other outlet?

I say “investigative approach” because I often feel like a criminal investigator from a TV show. I’m always gathering bits of information here and there. Especially with legacy systems; they’re almost always poorly documented. So you have the evidence of a design, the code is there. But the story of how it got there, how it works, and how you have to work with it to do the thing that you want to do with it… all of that may be a complete mystery. One that you have to solve.

I might be compiling notes from Google searches about the latest technology. I might be scouring through source code, maybe even downloading and running an application with a debugger. I might be walking up to someone’s desk and asking them questions. The point is I’m constantly compiling data from disparate sources and attempting to synthesize that into information that can help myself and my team understand what’s possible technically.

How do I “do Feasibility?”

So we know a bit about what feasibility is… how do we go about determining whether a project is feasible or not?

At the beginning of the project, I will direct my activities towards drafting a feasibility analysis report. This gives me a document where I can record answers to questions like the ones in the previous sections, and share the outcome of my research with the team and any stakeholders.

I treat it as a living document. It will continuously be updated and amended throughout the project as more is learned and decisions are made and changed.

The document isn’t just built by myself, of course. I’ll go over it with fellow engineers, my product manager, designer, stakeholders… anyone with information or vested interest. Their input helps further refine the document. It’s very much a collaborative effort.

I have yet to find a generic template that works for me. I’m open to suggestions, so if you have one, feel free to leave a comment! I’ve been developing different versions of a template as I’ve been doing this kind of work more formally.

What ends up in the feasibility report is usually some variation of the following

1. An overview of the options.

2. Potential trade-offs between the options. Pros/Cons.

3. A recommendation of which option.

4. Some additional context and background.

I’ll also put links to supporting documents as well. These might be architectural diagrams, architectural decisions records, conversations logs; anything that might be relevant.

I consider myself to be done with the first draft once the document answers enough questions about the implementation of a solution to a problem so that the development team has a solid basis of information upon which to begin implementation.

Now aside from feasibility analysis, there are other important aspects to my role as well. I view the tech lead role as a mixture of project management, software architecture, technical advocacy, and being a player/coach. Yes, even still coding. I plan to write more posts that are specific to those functions in the future.

So that’s a snapshot of where I’m at in this journey. I hope for anyone in a similar position that sharing this sparks some ideas and maybe even helps you to move from clarity to ambiguity, wherever you are on your path.