Gatsby Starter Blog RSS Feed

Shortening long feedback loops iteratively

Tue, 10 Sep 2024 20:26:02 GMT

TL;DR;

Feedback loops, especially short ones, are extremely important for developing high quality software
A rapid feedback loop of < 5-10 minutes is not always possible. If people or manual steps are involved, days may not even be possible.
Feedback loops can be shortened over time with iterative releases and small improvements.
When fixing a bug or finding an issue, we can ask ourselves “What would have helped us find this sooner?” Several iterations of this sort can quickly add up to massive gains in shortening feedback loops.
- We can apply this to the development of new features as well through the use of Vertical Slices and early demoing to product owners and stakeholders.

Feedback loops are a key aspect of any system. Software is no different.

Lately, I’ve been thinking a lot about feedback loops and cycles. An important part of being able to move quickly is getting feedback quickly so any corrections can be made as close to the source as possible. As engineers, we excel when this feedback loop is very short indeed. This is a big benefit of certain practices like Test-Driven Development.

But Enterprise software can be challenging. It’s not always possible for important feedback loops to happen in the span of seconds, or even minutes. Sometimes, feedback loops can even take weeks or months.

How many times have you been fixing a bug and realized the code that causes the bug has been checked in for months without problems? The cycle from the point of the bug being introduced and it being fixed has been a very long one. The context from the work done when the bug introduced may be lost. It could even be that the engineer that wrote the original code is no longer with the company.

A simple first step for shortening future cycles is asking ourselves: “What information could have helped us get this feedback sooner?”

It doesn’t need to be a large architectural change, or massive sweeping code change to make our lives better. Iterative improvements add up over time. They take on similar elements as compounding interest.

As we develop the practice of easing our pain one step at a time, future steps become easier to take. And by working on bringing the feedback loop back closer to the original context, we can also increase the options we have available to use for shortening the feedback loop. Perhaps you can start using runtime asserts, or improved logging, or compile-time feedback for code issues.

We can apply these thoughts to developing new features as well.

The sooner we get feedback on new features we develop, the cheaper it is to react to that feedback. We can use techniques like Vertical Slides combined with early and frequent demos to product owners and stakeholders to help guide our work through a new feature.

The longer you wait to get feedback on a new feature, the more painful it can be to react to feedback. We start experiencing potential pains around excessive rework, or wasted time from building the wrong feature.

Rapid Prototyping

Mon, 26 Sep 2022 17:31:04 GMT

Rapid prototyping is using the scientific method to quickly (usually within a single day) prove an approach to solving a problem.

For software engineers, rapid prototyping is usually used to test a technological solution’s usability and functionality. Rapid prototyping can also be done to quickly create testable UI/UX experiments that can be presented to a group of users to identify the best design. Rapid prototyping does not always include writing code or building software.

Principles

These are the principles that should be followed during the rapid prototyping process:

Always investigate the parts of the problem that is least understood first.
Usually investigate the easiest parts of the problem that are least understood first.
Always use the scientific process to investigate the solution.
Always take the time to clearly demonstrate the results of the experiments used to investigate the solution.
Always look for ways to demonstrate your prototypes and experiment outcomes on a daily cadence.

Process

For each problem:

Identify the Problem

1. Define who the problem is being solved for

When attempting to solve a problem, identify the stakeholders who are experiencing the issue. Knowing the people allows you to better target the solution and understand the underlying problems. It is rare that a problem is simple.

For example, you might be told that you need to figure out how to create an HLS stream from a set of files - video, captions and secondary audio. That seems like an easy problem, but the audience can matter greatly. Is the audience technically savvy enough to be able to get an OAuth token with the correct scopes and call an API endpoint that has dozens of required parameters? Or must the solution abstract all requirements in as simple a method as possible so that they do not have to understand the process before starting?

The audience is an integral part of the problem to solve. And there may be multiple audiences! Identify the problem for EACH person that needs the solution!

2. Define what the person wants to be able to do

The next most important part of identifying the problem is describing what the person wants to do. Try to avoid placing a specific solution in this statement. Do not write: “Joe wants a button on the lower left of the page that processes the form through system X” - that isn’t really what Joe wants (though that might be what Joe insists on!). A better statement might be, “Joe wants to be able to send the invoice information to system X.” The new statement opens the door to finding the best possible solution for what Joe needs.

3. Define why the person wants to be able to do it

The final part of the problem statement is crucial when someone is trying to implement a solution. WHY someone wants to be able to do something allows the solver to change direction and pick a better solution if the original path ends up being a dead end. For example, suppose Joe wants to be able to send invoice information to system X because system X is the system of record for that information. In that case, the solver will need to ensure the information gets to system X. They will realize that it’s not an acceptable alternative to send that information to system B instead - unless system B ALSO sends the information needed to system X.

Investigate a Solution

1. Identify the unknown or assumption about the solution that will be tackled next

Given any problem and a potential solution, there will be proven hypotheses about the answer, unproven hypotheses that we believe to be true or false (assumptions) and unproven hypotheses that we don’t know to be true or false (unknowns).

Categorizing each hypothesis in the buckets of proven, assumed, and unknown can be a powerful way of prioritizing the work needed to establish a solution. Remember that a proven hypothesis must be able to be demonstrated, even if the team didn’t create the demonstration.

When prioritizing, follow this order:

Prefer investigating unknowns to assumptions
Prefer investigating the most difficult items that can be proven the quickest first

2. Advance a hypothesis about the unknown or assumption and identify the quickest way to test (prove or disprove) the hypothesis

A hypothesis proposes that, given specific inputs, a particular outcome will be achieved. For example, Terraform can be used to provision an AWS S3 bucket with publicly accessible contents for any source. The inputs are not necessarily explicit in this example. They may need to be investigated further, but the outcome is crystal clear, and the hypothesis can be proven or falsified through an experiment. The experiment, in this example, might be following the Terraform documentation to create an AWS S3 bucket and reviewing the resulting bucket in AWS to see if it has the expected properties - perhaps by downloading a file from the bucket from multiple browsers on different machines in different locations.

3. Execute the test

Once the best and quickest test approach has been identified - get it done! The idea is to get the data you need to prove or disprove the hypothesis as quickly as possible - be aware this may not involve any coding or even using an application.

It is important to remember that executing a test usually involves more than a few unknowns - things go wrong! When they do go wrong, you will want to identify the following items quickly:

Do I need to resolve the issue, or can I go around it?
Is there another way to execute the test that I can try out?
Is there another test I can perform to get the data I need?
If this is the only way forward, and I need to solve the problem, how long should I spend on it before reaching out for help? And what is the best source for help to use?

4. Record the results and use the results to build a demonstration.

When the test is complete, you should have some data that can be used to prove or disprove your hypothesis. Take the time to record the uncovered data, and ensure the results can be shared with the audience intended for your prototype.

Recording everything can take more time than executing the test! That is okay; demonstrating your test results is at least as necessary as performing the test in the first place.

Make sure the demonstration of the results is compelling, clear and appropriately presented for your audience - the information you provide should help your audience understand what the test results imply and build consensus about the next steps to proving the hypothesis.

5. Identify any additional unknowns or assumptions about the solution that have been uncovered

Tests usually do not provide data that proves or disproves anything conclusively without any possibility of disagreement. In most scientific studies, the conclusions section includes paragraphs of ideas about how to investigate the hypothesis further to clear up additional identified assumptions or unknowns discovered during the study. The conclusion almost ALWAYS recommends further tests and investigations.

Don’t be discouraged if your tests turn up more unknowns than you had before running the test! Further understanding the hill that needs to be climbed to prove or disprove your hypothesis is an excellent outcome of your tests. Record your new unknowns and uncovered assumptions, and use that information to identify the next test that should be run.

Demonstrate Results

1. Gather discovered data and feedback

Data is the results of your tests and should not include any interpretation of what has been found. Here is an example of the difference between data and information:

Data	Information
Twelve percent of the requests to the endpoint returned a 404 error.	The endpoint has a high enough failure rate that, in order to use it and provide consistent results, we will need to retry our requests up to five times.
There are three documented methods available to use the service and get the data required.	There are three options to get the required data, and we will need to test each to determine which methods are the best option for our requirements.

Feedback is another significant output of your tests and the overall process. Feedback is information, requests or discoveries that come from what you’ve learned or from what has been gathered through the “demonstrate results” cycle. Feedback can come in the form of discovering additional unknowns, new existing assumptions, changes in the approach, problem statement or desired outcome.

2. Convert the data into information

The data is interesting - and should be recorded and accessible to your stakeholders and team - now and in the future. However, it’s not particularly useful on its own. Take a look at the data, and offer an interpretation - what does the data mean? How does it affect your hypothesis? What changes should be made to the thesis? Should there be changes to the next step or experiment? Does the data point strongly that proving or disproving the hypothesis is complete?

3. Tell the story with the information

Information is excellent - it is a great way to explore the data with the consumers of that information. It can guide and inform the process. However, it can also be boring, and a lot of information can be hard to synthesize, understand, and act on. The information gathered in your experiments is to indicate and decide upon action.

How do you build consensus around a course of action? Through telling a story. Find a way to explore the information - to explain why it is what it is and how it leads you to the conclusions you have reached. Whether that conclusion is “more tests needed - and here’s the next one” or “we’ve proven the hypothesis - the prototyping is complete,” the story carries the consumer along. It puts together a clear and compelling picture of what should be next.

4. Show something that demonstrates the story

Stories are great. And sometimes, just reading a story is an inspiring experience. But these days, SHOWING your story is usually the most effective way of sharing what you have learned. Think about how you can show what you’ve learned in a way that your audience can easily understand and enjoy. Is it a quick demo of the click-through website that shows how to get the work done? A graphic with a couple of bullet points? A video that walks them through the problem, your data, and the interpreted results? Maybe it’s a course built in Simon?

Spend some time creating a presentation. The experiments and the tests - these are important - but to finish a prototype, you need to build understanding as well as consensus about the next steps - and a good demonstration can’t be beaten to meet those goals.

5. Gather feedback from the demonstration

If you told a good story and demonstrated it well, your audience will be invested in the outcome and may have valuable feedback about what you’ve discovered. This feedback may help you decide what tests need to run next or give you a different direction - even a different hypothesis!

Record the feedback, and identify your action items. Then, do whatever is next!

Definitions

Word	Definition
hypothesis	A supposition or proposed explanation made on the basis of limited evidence as a starting point for further investigation.
scientific method	A method of procedure that has characterized natural science since the 17th century, consisting in systematic observation, measurement, and experiment, and the formulation, testing, and modification of hypotheses.
user story	A user story is a tool in Agile software development used to capture a description of a software feature from a user’s perspective. The user story describes the type of user, what they want and why. A user story helps to create a simplified description of a requirement.

Resources

How to Easily Update Dependencies with Supporting Packages

Mon, 12 Sep 2022 19:14:44 GMT

Photo by Alfons Morales on Unsplash

One of your dependencies needs to be upgraded, but it has several plugins or supporting packages. How can all of these packages be updated efficiently? Using ESlint on a sample project, this post will show an easy way to check and update all of these packages.

npm-check-updates

The npm-check-updates library allows you to check what updates are available for your dependencies. We want to check for updates on any packages that have a common word in their name, so npm-check-updates accepts as an argument a package name or regex. Execute the following in the root directory of the project with the name of your dependency.

npx npm-check-updates "/.*eslint.*$/"

The regex will match all packages that have that word in the name:

For each package matching the regex, you will see the current version and the latest version. Check that the list of packages includes all that you want to update. If not, adjust the regex.

Notice the color-coding of the version numbers. Any versions that are colored red indicate a major version, cyan indicates a minor version, and green means a patch upgrade. To upgrade every package on the list to the latest version, run the same command, but with the -u flag. This will modify package.json to have the latest version numbers.

Lastly, run npm install to install the new versions.

Before finishing, run any tests and linting checks. Changes to code will likely be needed depending on the upgrades done.

TypeScript Utility Types

Tue, 16 Aug 2022 23:38:36 GMT

Even if you’ve been writing TypeScript for a while, you might not have ran across the language’s built-in utility types. These come in handy and save you from having to manually implement some common type transformations. I’ll go over a few utility types we use often and how you can put them to work in your code.

Record

You can type an object with specific types for its keys and values using an index signature:

type Book = { [isbn: number]: string; };

With the Record type, you can represent the same object a bit more concisely:

type Book = Record<number, string>;

If syntax were the only difference, I’d prefer the index signature since the isbn key gives more detail about the intent of the type; however, the Record type is a lot more powerful!

Record starts getting really useful when you want to lock down the properties of an object. In the above example, the object’s properties can be any string, but here’s an example of using a union type of strings for the keys:

type Locale = 'en' | 'fr' | 'es';

type LanguageName = Record<Locale, string>;

const languages: LanguageName = {
  'en': 'English',
  'fr': 'French',
  'es': 'Spanish',
};

If I try to add German to this list, the compiler displays a nice error.

Another common use case is transforming the values of an object to a different type. Instead of maintaining a type that’s just used for the keys of other types, we can use the keyof keyword:

const languages = {
  en: 'English',
  fr: 'French',
  es: 'Spanish',
};

type SupportedLanguages = Record<keyof typeof languages, boolean>;

const appLanguages: SupportedLocales = {
  en: true,
  es: true,
};

Again, there’s a nice error if an unexpected property is used.

Partial

The Partial type makes all properties of a type optional. This is particularly useful for creating mock objects for testing. You can create a factory function that uses the desired type without needing to provide every value:

interface Profile {
  name: string;
  avatar: string;
}

const createMockProfile = ({ name: 'Mock User', avatar: 'test.jpg' }: Partial<Profile>): Profile => ({
  name,
  avatar,
});

const testProfile = createMockProfile({ name: 'Test User' }); 

console.log(testProfile); // { name: 'Test User', avatar: 'test.jpg' }

The opposite of Partial is Required—it makes all the properties of a type required.

Pick and Omit

Sometimes you just need a subset of properties from a given type. Instead of creating a new type with values that are duplicated elsewhere in the codebase, you can use Pick and Omit.

Pick takes the given properties from a type. For example, we use Pick to build custom React components that wrap other third-party components in order to simply the interface:

import Button, { ButtonProps } from '@mui/material/Button';

type CustomButtonProps = Pick<ButtonProps, 'color'>;

function CustomButton({ color }: CustomButtonProps) {
  return (
    <Button
      color={color}
      variant="contained"
  ...
}

This pattern helps enforce consistency since it limits the customization possible with props, but it also provides a simpler dev experience.

Omit works the opposite way: it filters out properties of a given type. This is useful when you want to use an existing type but overwrite one or more of its properties.

For example, maybe you have the concept of a “variant” in your design system and you need to expose it as a prop for a custom button, but the new component library you’re adopting already uses “variant.” You might try something like this:

import Button, { ButtonProps } from '@mui/material/Button';

interface CustomButtonProps extends ButtonProps {
  variant: 'success' | 'error';
}

This won’t compile because the custom variant type doesn’t satisfy the constraints from ButtonProps:

It’s valid to narrow the type, i.e. variant: 'contained', but you can’t overwrite the properties of other interfaces this way.

The way around this is to use Omit to first remove the property from the type and then extend that filtered interface:

import Button, { ButtonProps } from '@mui/material/Button';

interface CustomButtonProps extends Omit<ButtonProps, 'variant'> {
  variant: 'success' | 'error';
}

Both utility types can, of course, be combined and use multiple keys to make them even more expressive:

interface CustomButtonProps extends Pick<Omit<ButtonProps, 'variant' | 'size'>, 'color' | 'type'> {
  variant: 'success' | 'error';
  size: 'tiny' | 'big';
}

And Many More

Utility types can save you a lot of time and reduce complexity in your codebase. There are a lot more than what’s covered here—you can try them all out in the official TypeScript Playground. These examples just scratch the surface of what you can do with utility types and I hope they can help you improve your TypeScript.