The elephant in the room: Engineering in the dark

There is a parable about five blind monks who observed an elephant. It was separately assumed to resemble a bat, snake, tree, wall, and rope. This was because the five only had their context of the ear, trunk, leg, side, and tail (respectively). When you put together all the pieces, you have an elephant. In project planning, the uninitiated are afraid to look at or talk about the whole elephant in the room and its parts.

I am not a Product Manager, but I love talking about products! While managing kitchens and working in a collectively owned food business, I reveled in the conversations about defining the company and how to keep our products “on brand” and make them do what they should: spark joy and work as expected. My favorite conversations as an Engineer have been about the product we are building, the new feature, and having one service the other. Of course, you have to understand the context of the features we create.

I briefly read the brief

One reason I enjoyed cooking professionally was that it affected people. The meal I cooked could make or break a date, birthday, or night out. Becoming a people pleaser had become engrained as a part of Hospitality. The focus here is always on quality over quantity because a people-pleasing mentality fails when you change a product to make everyone happy.

Years ago, I worked in a new restaurant where the owners hoped to appeal to everyone even though the concept was specific to a population and demographic. The menu offerings grew in many directions and the restaurant could not stay open. Trying to make a restaurant, or any product for that matter, appeal to everyone requires you to make a lot of compromises and cast too wide a net. The focus becomes unclear, and there’s little chance of spotting your target somewhere in a large blurry mass.

The same goes for feature development. There have been projects I worked on where newer Engineers begin writing code before understanding the extent of the feature. API routes that search a table across one filter and auth functions that don't verify the user exists are lines of code you can tally for resume stats. But can you count on them to be functional for the project?

Let's take the auth function as an example. Once, I worked with an engineer who implemented JSON Web Tokens (JWT). Using the JWT, our Back End would verify the user was active. The payload had identifying data that got decoded and extracted from the JWT. If this identifying data existed in the payload, an identifier was logged and the token was authenticated. Did you catch it? An opportunity was missed. Like so much political discourse: data should be verified. The Engineer who wrote it forgot to verify this user information exists in the database. After code review, I noted a payload like the following would still be authenticated.

{
    "email": "fake_email_magoo@BadDomain?#.boobooboo",
    "user_id": True,
    "unexpected_key": "Oops",
}

The Engineer didn't consider the use case of the authentication token. Understanding the context, we need to ensure:

1. Only account-holding customers have authentication tokens.

2. Data in the authentication is valid and expected.

3. The token is not expired.

4. Personal identifying information is not shared in auth tokens.

Light the way

A definition of the parameters and refactor later and the auth token was secure. As a further measure, our team committed to explicitly defining features and partnering with QA to create testing criteria before feature development. The problem wasn't the Engineer, it was the lack of clarity on the feature. As team leaders, we need to give our newer members the tools to understand the context, examine the use case, and Engineer a solution.

Managing a kitchen prepared me to create software products because parameters and expectations must be set. I remember being a junior line cook, cooking in the dark with vague instructions and French culinary terms I was too afraid to ask about, and getting put down by fellow line cooks for not knowing Chef's expectations. Aside from the resilience, it taught me to ask questions along the way and not care too much if my queries were "obvious." These are the questions that grew my experience. My commitment to my team and our project is to stoke interest and care for our customers. This involves walking around the project with my team and discussing the details. Without this commitment, we're bound to be surprised to discover our elephant has tusks.