Michela Frecchiami

**3D illustrations are a trend of web design in 2021:** reality and virtual reality are getting closer and closer. The combination of 3D shapes and effects in the 2D space is a great example of this trend in action. This is the right time to start learning something new, then!

At Nebulab, every employee has a bunch of hours to spend on personal projects, trying new tools, or studying to improve their skills and professionalism, so I decided to spend some hours of my [Investment Time](https://playbook.nebulab.com/personal-growth/investment-time/) developing a new skill that is useful for creating trendy illustrations and animations. I want to share my design process and what I’ve learned along the way.

## Spline 3D, nice to meet you!

I’ve always been fascinated by 3D design. Several years ago I tried Blender but I found it very complicated: the environment was very far from the applications that designers like me use, and since it wasn’t a must-to-have skill at that time, I gave up very soon.

This time I approached again to the three-dimensional design by using a brand new tool that makes 3D easier for a not-3D designer like me. This tool is [Spline](https://spline.design/): its interface is very similar to the majority of other design apps like **Figma**, for example. On the left side, there’s the layers panel while the tools used more frequently are on the top of the window. On the right side, you can find all the other options like Global Settings, Shape options, Camera Settings, etc.

## Initial phase: copy, try, repeat

When I start to develop a new skill, my approach is: learning the foundation, seeing how others do it, and playing with features and effects. Mostly, **having fun.**

Since Spline 3D was launched quite recently, you won’t find tons of tutorials on YouTube but there is a useful [documentation](https://docs.spline.design/) that gives you an overview of what (and how) you can do with Spline. Moreover, there’s a library where you can find illustrations and animations for playing with all the features.

![iPhone 12 3D mock-up, by Spline 3D](https://cdn.sanity.io/images/kqgmf0g2/production/025512f4b8e8134e5685c24024004f3f5c314035-1680x1027.jpg?fit=clip)
*This is the original mock-up of the Spline library.*

![iPhone 12 3D mock-up, customized with the Nebulab website and brand color](https://cdn.sanity.io/images/kqgmf0g2/production/35badac7709f3f9ec8613d94bbd9e1a112b21fcf-1680x1027.jpg?fit=clip)
*This is the customized version I did, starting with the mock-up above.*


### Camera operations

One of the first things I’ve learned is how to change views by using camera controls.

* **[Option / Alt] + drag** to rotate the screen (camera).

* **Press [Space] + drag** to move the camera around the canvas.

These controls allow you to simulate different views of your canvas and let you understand how three-dimensionality works.

### Materials

In Spline, there’re **7 types of Material** thus the Lighting layer: initially, I was wondering about having more options for creating awesome 3D color effects, but then I sooner understood that mixing just two or three material layers thus the Lighting one, lets you create a lot of combinations and you can easily find yourself spending two hours or more on it because you can’t decide which one you like most! That’s why I think is better to complete the illustration as the first thing, adding some animations eventually, and then focus on the colors and lights. The simplest three-dimensional effect is given by the **Lighting** layer (try to fill your object with a color and move the Lighting layer above).

![Spline 3D, lighting material](https://cdn.sanity.io/images/kqgmf0g2/production/26e42163d282f174007aa0b35014236c9a350ca1-1680x896.jpg?fit=clip)

Adding a gradient by the **Gradient** layer seems a bit flat to me; a more precise method for adding gradient (or depth) to your objects is the **Depth** layer.

![Spline 3D, gradient vs depth material](https://cdn.sanity.io/images/kqgmf0g2/production/4f53e9f9ce19327d998a4750da1fd08003197cd6-1680x997.jpg?fit=clip)
*Gradient material vs Depth.*

## Playing with Material for creating something cool

Another design trend in 2021 is **holographic and reflective elements.** You can create these two effects using the **Texture** material: import your holographic background (stock images or created using Photoshop), and edit the texture properties until the result satisfies you.

[![alt](https://cdn.loom.com/sessions/thumbnails/b987486fc5ec4739982150c9e97e13d8-with-play.gif)](https://cdn.loom.com/sessions/thumbnails/b987486fc5ec4739982150c9e97e13d8-00001.mp4)

*An example of how to use the Texture tool for creating the holographic effect.*

Use **Fresnel** for creating a reflective effect like this ring I did:

[![alt](https://cdn.loom.com/sessions/thumbnails/360368ebe5fd40e8b46bab7bc5a2f322-with-play.gif)](https://cdn.loom.com/sessions/thumbnails/360368ebe5fd40e8b46bab7bc5a2f322-00001.mp4)

For each Material layer, you can set the mode property and the layer opacity as you’d in Photoshop (normal, multiply, screen, overlay).

### Tricks that can save your time

* You can **copy/paste material** from an object to another. **(▲)**

* With the **Cloner** tool, it’s possible to clone an object and you can set the number of clones you want, the *Type* (how the clones are placed on the canvas - radial, linear, grid), and you can adjust the position, rotation, and scale them.

* With the **Visibility** mode, you can display the wireframe of a 3D object (and that might be a cool effect for your artwork!).

**(▲)** While I was writing this article, Spline has released the Alpha II version that introduces the web app and the **Material Assets** feature: now is possible to save Materials as assets on your project!

[![alt](https://cdn.loom.com/sessions/thumbnails/f99dd970a5574e93a80cb4cfa5362576-with-play.gif)](https://cdn.loom.com/sessions/thumbnails/f99dd970a5574e93a80cb4cfa5362576-00001.mp4)
*The new feature, Material Assets, works like Figma.*

## Starting from a blank canvas

After the discovery phase, I felt ready to start with something simple like an infinite rotation of the Nebulab logo as if it was an app icon. Spline 3D lets you **import SVG** files and after the Alpha II version was released, you can use the **Extrusion** tool to transform flat shapes into 3D objects.

![Spline 3D, extrusion](https://cdn.sanity.io/images/kqgmf0g2/production/d36903c4141a571eaaefb59987465a70673f8418-1680x1291.png?fit=clip)

![Nebulab 3D logo](https://cdn.sanity.io/images/kqgmf0g2/production/f23079e867385dba280f291061465ae64d65e9d1-3584x2240.jpg?fit=clip)

## Let’s move it!

Now that I have the Nebulab logo as a shiny bold blue cookie, I want to add a simple animation. I browsed on Dribbble looking for some inspiration and then I opted for a rotating animation with a final ease-out motion.

### Understanding States and Events

At the top of the right menu, you can find States and Events. Playing with animations with Spline is pretty simple (like everything else 😃) also because you can see the preview whenever you want, by clicking the Play button on the topbar tools.

![Spline 3D, the animation preview is always available](https://cdn.sanity.io/images/kqgmf0g2/production/330dcd7d5bf7cd1ff5585d336e2be6a5d1e32fb0-906x198.png?fit=clip)

To make my first animation, I need two states:

* *Base State*, is the initial position or style of an object.

* *State 1*, which changes the previous state values.

You can change the position and/or the aspect of your object. In this example, I rotated the entire logo on its axis.

[![alt](https://cdn.loom.com/sessions/thumbnails/ed27166d1b6d43ba8a1b1f7fc589c3f6-with-play.gif)](https://cdn.loom.com/sessions/thumbnails/ed27166d1b6d43ba8a1b1f7fc589c3f6-00001.mp4)

Now, these two states need a trigger that you can add by the **Event** panel. (**Be sure to have selected Base State** and then add a new event). **Select the type of trigger for the event**:

* *Mouse up, down, hover*, that you can use to create a button and you can even link to an external URL.

* *Key up, down*, that is the same as the mouse types but it requires adding the key you want that triggers.

* *Start*, the animation will start by itself.

* *Look at*, this reply the cool effect of moving objects when the user pointer passes over the active area.

* *Follow*, the object is linked to your user pointer as a magnet.

I wanted my animation fired automatically, so I selected the *Start type*. I’ve previously grouped all the shapes that compose the logo, so I had one object to select for the event that I was creating. While the state to select, is *State 1*.

![Spline 3D, states and events](https://cdn.sanity.io/images/kqgmf0g2/production/f094307692892d64a34817160faa61abc5ba65ae-1680x1050.png?fit=clip)

You can decide to repeat the animation infinitely, or just once. Then you can select the **Transition** type; if you know a bit of CSS these names should sound familiar to you: linear, ease-in, ease-out, ease-in-out, cubic (which is like the CSS *cubic-bezier*). I’ve played with these all but in the end, I opted for the Spring transition because I like damping effect on this kind of animation. About the Spring transition, you can play with its values since you won’t find the combination that satisfies you.

[![A video showing 3D animation configuration](https://cdn.loom.com/sessions/thumbnails/4adb76bc402d4b558d099dae004a6a2f-with-play.gif)](https://cdn.loom.com/sessions/thumbnails/4adb76bc402d4b558d099dae004a6a2f-00001.mp4)

And that’s it! You can apply different effects to every single object by adding *State 1* on it and then add the object to the main event by the ***“Add a new object to event”* button.**

[![A short video of the Nebulab logo 3D-animated](https://cdn.loom.com/sessions/thumbnails/ba16d29395e2458aa393761f06939fef-with-play.gif")](https://cdn.loom.com/sessions/thumbnails/ba16d29395e2458aa393761f06939fef-00001.mp4)
*This is the final animation*

## Don’t limit yourself

As I said before, what matters is having fun! Having the freedom to create whatever you like lets you experiment with a greater variety of features, and makes you more confident with the tool.

![3D artwork done with Spline 3D](https://cdn.sanity.io/images/kqgmf0g2/production/eefd0a35280995051e73c67e691e681383f8a038-1680x1260.jpg?fit=clip)
*This is my first 3D artwork in which I played with materials, colors, and shapes.*

Even if it seemed simple (not a “WOW” illustration), I didn’t want to limit my experiments to what is trendy at the moment. I just wanted to create something for myself, as an artist draws to express their feelings. Ok, well, maybe I’m exaggerating, but what drove me when I designed that artwork was just creativity, nothing more. I’m pretty sure that looking at it in a month, I’ll say to myself something like *“How could I be so proud of that illustrationMouse up, down, hover,”* and then I’ll be back to revisit it, trying to push my boundaries a bit more.

![The Nebulab Solar System in a 3D version](https://cdn.sanity.io/images/kqgmf0g2/production/6d1e6fabee08ed85aaa418b928d34822fae9785a-1680x1260.jpg?fit=clip)
*I’ve redesigned all the planets of the Nebulab website with Spline. In this illustration, I included them in the Solar System.*

![3D character done with Spline 3D](https://cdn.sanity.io/images/kqgmf0g2/production/7519216a0df3a358ebba7d983ede50e569d51b7b-1680x1150.jpg?fit=clip)
*My first 3D character, a tribute for the running Olympic games.*

## How 3D design supports your workflow

Even if you’re not a 3D artist (and if you’re reading this article I suppose you aren’t) knowing how to create 3D objects or scenes can be very useful. You can create tailored mock-ups for a mobile app, for example, or adding some catchy objects that interact with the user pointer on your website.

![The Blog page hero with some 3D objects](https://cdn.sanity.io/images/kqgmf0g2/production/abc58349dae18f451b8da3506d386b92cd952481-1680x1260.jpg?fit=clip)
*I’ve tried a white version of the Blog hero with some 3D objects that interact with the pointer.*
[See the sample in action.](https://www.loom.com/share/0192deb8d73b41fdb55ed361f0b1c3a8)

[![Final animation videoclip](https://cdn.loom.com/sessions/thumbnails/0384abffdff0454c9b94eda02ccc272e-with-play.gif)](https://cdn.loom.com/sessions/thumbnails/0384abffdff0454c9b94eda02ccc272e-00001.mp4)
*You can even use this to show off a new website or mobile app, with a trendy minimalistic animation like this one.*

Surely, there’re tons of mock-ups you can download and use but having the flexibility to create your own is extremely better, even in terms of marketing.

I’m happy to have spent some hours of my *Investment Time* learning Spline 3D! Truthfully, I’m still experimenting with it, but what I have done so far has given me an incentive to continue learning this modern, trendy tool and to go deeper into the 3D world.

Experimenting with Spline for 3D Design

Andrea Vassallo

In this article, we are going to show how you can create a [NextJs](https://nextjs.org/) project with [Storybook](https://storybook.js.org/) and [TailwindCSS](https://tailwindcss.com/).

Before starting, I want to explain who are the actors and why it should be better adding them to our frontend application.

### NextJS

[NextJS](https://nextjs.org/) doesn’t need a lot of presentation. If you are here, you probably already know what NextJs is and why we should use it to build robust applications.

NextJs is a great [React](https://it.reactjs.org/) frontend framework, and it’s mainly used to build SEO-friendly applications since you can use three different types of rendering/pre-rendering methods:

* SSG (Static-site generation) the HTML is generated at build time and will be reused on each request,

* SSR (Server-side rendering) the HTML is generated on each request using a node server, so the response is SEO-friendly.

* CSR (Client-side rendering) the normale React behavior, the response is simply Javascript run by the client.

### TailwindCSS

Tailwind is one of the most powerful libraries to build your application style using HTML classes. [TailwindCSS](https://tailwindcss.com/) implements a ton of dynamic classes which apply different style rules to your application, and it is fully customizable using the configuration file!

Initially it will take time to understand which are the correct classes you need to use to build your interface, but one of the coolest thing in Tailwind is its super documentation.

By the way, the 2.0 version has recently been released with a lot of new features.

### Storybook

[Storybook](https://storybook.js.org/) is a great library that is mainly used to render our application components outside the NextJs environment. This means that you can check your components UI without making real queries or fetching data. You can also figure out how the application components change based on the passed props.

Storybook is more powerful when used with well-organized components, for example, using [Atomic Design(https://bradfrost.com/blog/post/atomic-web-design/).

**Example**

You will probably create your custom `Button` component in your project that will be rendered differently based on the passed props or the fetched data. With Storybook, you can check all the UI changes applying custom props from the Storybook panel or stubbing all your requests.

### TL;DR

Here you can find the fully configurated [project](https://github.com/nebulab/nextjs-storybook-tailwindcss)

## Let’s start!

For this article, I won’t split the application into components to be more direct. It would be best to do it in a real application to avoid using the `index.js` page directly.

The best practice is writing components splitting them by context using a great file structure:

* React documentation about components: [link](https://it.reactjs.org/docs/components-and-props.html#extracting-components)
* Atomic Design pattern about components structure: [link](https://bradfrost.com/blog/post/atomic-web-design/)

### Create the NextJS app

First of all, run this command to create your NextJs project:

```
npx create-next-app --use-npm nextjs-storybook-tailwindcss
```

and navigate inside the project directory with `cd nextjs-storybook-tailwindcss`.

### Run your application

```
npm run dev
```

### Refactor the default code

The `create-next-app` command creates the project with some unnecessary configuration since we’ll use **TailwindCSS** to build our style.

Replace the content in `pages/index.js` with:

```
const Home = ({ article, showImage }) => {
  if (!article) return "The article wasn't found!"

  const {author, company, image_url, content} = article

  const Image = showImage ? (<img className="w-24 h-24 rounded-full mx-auto md:flex md:self-center"
    src={image_url} alt="A beautiful cat" width="200" height="200" />) : ''

  return (
    <div className="w-96 mx-auto">
      <div className="h-screen flex items-center">
        <figure className="lg:flex bg-gray-200 rounded-xl p-8 lg:p-4">
          {Image}
          <div className="pt-6 lg:p-4 text-center lg:text-left space-y-4">
            <p className="text-lg font-semibold">{content}</p>
            <figcaption className="font-medium">
              <div className="text-blue-600">{author}</div>
              <div className="text-gray-500">{company}</div>
            </figcaption>
          </div>
        </figure>
      </div>
    </div>
  )
}

Home.defaultProps = {
  showImage: true
}

export const getServerSideProps = async () => {
  const response = await fetch('http://localhost:3000/api/article')
  const data = await response.json()

  if (!data) return { props: {}}

  return {
    props: {
      article: data
    }
  }
}

export default Home
```

Add your first API:

```
touch pages/api/article.js
```
```
const Article = (_, res) => {
  res.statusCode = 200
  res.json({
    id: 1,
    author: 'Andrea Vassallo',
    company: 'Nebulab',
    image_url: 'http://placekitten.com/200/200',
    content: 'The cat is a domestic species of small carnivorous mammal.'
  })
}

export default Article
```

Remove the CSS file: `styles/Home.module.css`:

```
rm styles/Home.module.css
```

![Nextjs without style result](https://cdn.sanity.io/images/kqgmf0g2/production/cf125dfe5106852987ebfd778e133fe4566ef324-537x357.png?fit=clip)

![Man pointing thumb down](https://cdn.sanity.io/images/kqgmf0g2/production/f804d6533a925773c96bc9055cd7aae96d76c578-640x480.gif?fit=clip)

The result is an ugly and boring HTML page.

**Let’s go applying our awesome style.**

### Install TailwindCSS

*Why the documentation isn’t enough in this case?*

Because NextJS came up with a bunch of pre-configured services like Babel and [PostCSS](https://postcss.org/) and we have to TailwindCSS with them.*

Reading the [TailwindCSS documentation](https://tailwindcss.com/docs/installation), you’ll see that we need three different libraries to complete the installation:

* tailwindcss

* postcss

* autoprefixer

We don’t need to install postcss and the autoprefixer libraries since they are already installed in NextJs.

Run these commands to install TailwindCSS:

```
npm install --save-dev tailwindcss
```

Unfortunately, we can’t use `npx tailwind init` to create the configuration file since it’ll check if you have installed the `autoprefixer` library.

Let’s create the configuration file adding the `tailwind.config.js` file:

```
touch tailwind.config.js
```

with the default configuration:

```
module.exports = {
  purge: [
    // This is not present inside the default configuration
    // but it's good to build your production application
    // Read more about this here: https://tailwindcss.com/docs/installation#building-your-css
    './pages/**/*.js',
  ],
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}
```

### Configure PostCSS

To configure PostCSS we have to override the [NextJs default one](https://nextjs.org/docs/advanced-features/customizing-postcss-config):

Install the dependencies:

```
npm install --save-dev postcss-flexbugs-fixes postcss-preset-env
```

Create the `postcss.config.js` file:

```
touch postcss.config.js
```

and fill it with the default configuration as well:

```
module.exports = {
  plugins: {
    'postcss-flexbugs-fixes': {},
    'postcss-preset-env': {
      autoprefixer: {
        flexbox: 'no-2009',
      },
      stage: 3,
      features: {
        'custom-properties': false,
      },
    },
  },
}
```

Add the `tailwindcss` plugin to the top of the plugin list:

```
module.exports = {
  plugins: {
    tailwindcss: {},
    ...
  },
}
```

### Include Tailwind in your CSS

Add these three lines of code to the top of this file: `styles/globals.css`:

```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

### We made it

Check your application homepage; the result should be similar to this one:

![Tailwind result](https://cdn.sanity.io/images/kqgmf0g2/production/8610b447fdcea90e798a8e33440326e498f8cbba-485x292.png?fit=clip)

![](https://cdn.sanity.io/images/kqgmf0g2/production/ef653b4c8ced24daaf9d3b865d207d11b7b905bb-700x394.gif?fit=clip)

## State of mind

From here on, it’ll be a breeze building beautiful component with Tailwind, but we need to answer a couple of questions about testing:

1. How is this component rendered when the article data isn’t found?

2. How can we check all the component variants at any moment without changing the code?

[Storybook](https://storybook.js.org/) will help us to accomplish both.

### Install Storybook

The default `npx sb init` command that is used inside the official documentation installs libraries that we don’t need and adds a bunch of files that we don’t use.

For that reason, I usually prefer to use the `from scratch` configuration.

```
npm install --save-dev @storybook/addon-actions @storybook/addon-essentials @storybook/addon-links @storybook/react
```

Add the Storybook commands inside the `package.json` scripts:


```
"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "storybook": "start-storybook -p 6006",
  "storybook:build": "build-storybook"
}
```

Copy this piece of code inside the `.storybook/main.js` file

```
module.exports = {
  "stories": [
    // Paths to the story files
    "../pages/*.stories.mdx",
    "../pages/*.stories.js",
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials"
  ]
}
```

Copy this piece of code inside the `.storybook/preview.js` file

```
// Import the global style enabling tailwind classes
import '../styles/globals.css'

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
}
```

### Add a story

For each page or component that we want to tell using a `story`, we need to create a file called `component-name.stories.js`.

In this case, we want to create the `index.stories.js` inside the `pages` dir:

```
import Article from './index';

const articleMock = {
  id: 3,
  author: 'Dave Canterbury',
  company: 'Bushcraft 101',
  image_url: 'https://via.placeholder.com/200/200',
  content: 'David Michael Canterbury born September 19, 1963 is a survival expert'
}

const Story = (props) => <Article {...props} />

// Here we export a variant of the default template passing props
export const ArticleStory = Story.bind({})
ArticleStory.args = {
  article: articleMock,
};

// Here we export a variant of the default template passing props
export const EmptyArticleStory = Story.bind({})
EmptyArticleStory.args = {
  article: null,
};

// Here we export the default component that
// will be used by Storybook to show it inside the sidebar
export default {
  title: 'Article',
  component: Article,
  argTypes: {
    showImage: { control: 'boolean' },
  },
};
```

### Run the Storybook server

```
npm run storybook
```

![Storybook result with style](https://cdn.sanity.io/images/kqgmf0g2/production/6b98a19deccff277aaa00d736aff13aa969a23ac-846x906.png?fit=clip)

At the time of writing there is a chance you might run into this [bug](https://github.com/storybookjs/storybook/issues/12668). You can fix it with this [solution](https://tailwindcss.com/docs/installation#post-css-7-compatibility-build).

## That's all

Your project is ready to be built using a robust framework and beautiful style with an easy way to check component behavior in isolation!

I hope that you found this article helpful and easy to read.

Do you need the [Typescript](https://www.typescriptlang.org/) version? Let us know with a comment.

### Follow up story - use TailwindCSS and Storybook with SCSS

NextJS side this isn’t a problem, you need just to install the `scss` library using `npm`.

```
npm install sass
```

Rename the `styles/globals.css` to `styles/globals.scss` and fix the `_app.js` and `.storybook/preview.js` style imports.

and replace the TailwindCSS style import from this:

```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

to this:

```
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";
```

**And Storybook?**

![Storybook SCSS error](https://cdn.sanity.io/images/kqgmf0g2/production/59838f648762570d289c5201a0bf7848015ae22e-1042x410.png?fit=clip)

It seems that Storybook doesn’t recognize the SCSS syntax, and for this reason we need to extend the library [Webpack](https://webpack.js.org/) configuration adding the `sass loader`.

The Webpack loader is used starting from the end, and this means that the `sass-loader` should be added at the end of the loader list.

Here you can find the `.storybook/main.js` file with the correct configuration:

```
module.exports = {
  stories: [
    // Paths to the story files
    "../pages/*.stories.mdx",
    "../pages/*.stories.js",
  ],
  addons: ["@storybook/addon-links", "@storybook/addon-essentials"],
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.scss$/,
      use: [
        "style-loader",
        "css-loader",
        "postcss-loader",
        // Add the sass loader to process scss files
        "sass-loader",
      ],
    })

    return config
  },
};
```

Using Tailwind and Storybook with Next.js

Alessandro Desantis

Let’s consider two engineering managers, John and Jane. They have the same seniority, they both work on similar projects in similar conditions and their teams are both terribly smart.

John insists on personally reviewing and approving every change, no matter how small. This doesn’t just concern the codebase: if an engineer wants to try a new productivity tool with the team, they have to go through John. If the team wants to move an internal meeting to a time that better suits everyone, she has to go through John. Every little detail is scrutinized and torn apart to make sure John’s team don’t waste their time on “useless” initiatives.

Jane, on the other hand, is more comfortable with experimenting. She doesn’t require the team to ask her approval for everything, but she is there to support them when they want to try something new, and helps them validate initiatives by setting clear goals and metrics that make sense for them. Then, she takes successful experiments and acts as the team’s champion in the larger organization, implementing these initiatives at a higher level.

Which team do you think will be happier, more productive and more innovative — John’s or Jane’s?

## Bottleneck Managers Create Permission-Centric Organizations

John is the typical example of a **Bottleneck Manager**. We all know at least a few Bottleneck Managers: they hoard information and authority and require teammates to go to them for every little thing. Want to try a new tool? Ask your manager. Want to move a meeting? Ask your manager. Want to change the name of a Slack channel? Ask your manager.

Put enough Bottleneck Managers together and you have an alienating workplace where there’s a process for everything and no way to change that process, until one day you realize you’ve just been doing the same thing for the past five years and you’ve become irrelevant two years ago anyway, but no one has told you because they were too busy writing code. You have, to put it briefly, a **Permission-Centric Organization**.

Permission-Centric Organizations are the natural result of one or more of the following factors:

* **Lack of trust**: his goes both ways. Managers may not trust their teams to make sensible decisions, or teams may not trust their managers to make good use of the results of their decision-making. If a teammate wants to try a new technology but knows their manager will scoff at it, they may not even propose it, to avoid the uncomfortable feeling of rejection.

* **Lack of time**: managers want to make sure everyone on their team is using their time in an optimal way. In doing so, they may overly centralize the decision-making process, to the point where the team is not free to do anything but write code. In some companies, managers will allocate all of the engineers’ time to “busywork”, leaving no room for anything else.

* **High cost of error**: if you have a proven process and battle-tested tools in place, it’s scary to try something new. Sure, the new tool/methodology may improve your work by an order of magnitude, but what if it doesn’t work and you end up alienating your stakeholders? The more successful you get, the more this becomes a problem.

* **Lack of competency**: when team members are not competent enough to experiment in a safe, productive way, management may create constraints around experimentation and take the reins of the engineering process. This may also come from the team members themselves: if they are not (or don’t feel like they are) competent enough, they may avoid trying new ideas for fear of making a mistake.

These are all valid problems. If you’re running a successful company, you want to make sure innovators are competent, you want to trust them and you want them to trust you, you want to dedicate time to the things that really matter, and you want to eliminate or minimize any room for mistake.

However, there’s a way to have your cake and eat it too. You can have all of the above, without hindering your team’s ability to come up with new ideas and validate them. The way to do it is to stop being a Bottleneck Manager and start being a **Multiplier Manager**.

## Multiplier Managers Create Feedback-Centric Organizations

Unlike John, Jane is a Multiplier Manager. A Multiplier Manager supports their team, but also allows them to make their own decisions. They’re proactive in identifying opportunities, but let the team capitalize on opportunities in their own way. They create processes and boundaries for safe innovation and encourage the team to pursue their ideas. They are — by far — the best kind of manager you’ll ever work with.

Multiplier Managers are the bread and butter of **Feedback-Centric Organizations**. These are workplaces where you can — and are strongly encouraged to — run an initiative by your manager to get feedback on it, without first having to ask permission. They are workplaces where ideas move freely from one desk to the other, in continuous evolution.

Just like a Bottleneck Manager and a Permission-Centric Organization are identified by a particular set of dysfunctions, Multiplier Managers and Feedback-Centric organizations exhibit and promote most (preferably all) of the following virtuous traits.

### Provide context about the business

Lack of transparency about the business context and business goals of their organization is one of the most common reasons why people don’t feel like they’re empowered to change their surroundings — withholding information may save your team some time, but it also prevents them from providing their perspective and putting their own twist to what you’re doing.

Multiplier Managers make sure to share all relevant information with their team. Not just what they’re doing, but why they’re doing it and whom they’re doing it for; any decisions that are made, and why they’re being made; who’s responsible for what; any processes the team follows and the rationale behind them, and anything else that might be of interest to other people.

Once the amount of information is too much to be pushed to all teammates all the time, they start publishing it instead and give their teammates an easy, clear way to access it, so that they don’t risk wasting the team’s time with anything they don’t find interesting. This may take different forms: a shared Google Doc, an entire shared folder, a company playbook, meeting recordings or a bunch of those — whatever works for the company and how people communicate.

## Define what “good” innovation looks like

This is where bureaucracy and innovation meet: the best approach to innovating is by doing it within clear constraints and with a streamlined process. Constraints give your team members a way to frame their ideas in a way that makes sense for everyone, and process lets them validate and execute their ideas in a controlled way.

Here’s the stuff that Multiplier Managers are concerned with:

* What kind of innovation is good innovation? Is it okay to propose rewriting a perfectly working project in a new, shinier technology? Is it completely forbidden, or should it just be a time-boxed endeavor?

* How do we determine if an idea is successful? Do we need to set clear business metrics in advance, or do we use more qualitative metrics? Does it depend on the context?

* What’s the process for collecting feedback? Even more important, what’s the process for understanding whom to collect feedback from in the first place? What kind of feedback should be asked for at what points during the process?
Your mileage may vary, but the mere act of creating a process will be beneficial to your team and make it known that not only is it okay to experiment, it’s encouraged and codified.

### Use automation to create safeguards

If your organization is run by humans, someone is bound to screw up at some point. While Bottleneck Managers run from mistakes and pretend everything can be perfect all the time, Multiplier Managers embrace chaos and try to minimize the ways in which things could go wrong, the cost of things going wrong, or both.

Multiplier Managers use automation to their advantage: they know that systems are dumb and infallible while people are smart and fallible. This leads them to give their team ample freedom to innovate and move quickly *without* having to ask permission. At the same time, they create automated safeguards around the critical aspects of the company’s infrastructure to protect them from human error.

The most obvious example of this is creating a CI pipeline and setting up the proper telemetry to ensure developers can iterate on the codebase as quickly as they can think, *without* running the risk of breaking the app with a bad deployment. Removing the human element from the approval process is key to boosting speed and creativity in the organization.

### Promote technical excellence and innovation

As you create more room for experimenting and taking ownership, you should also make sure you’re promoting technical excellence at all levels of the organization. Having the right skillset empowers individual contributors to spot and seize opportunities for improvement, and it empowers managers to recognize and support innovators.

Before you start firing people, though, make sure those “code monkeys” on your team are not monsters of your creation. Even the most proactive engineer in the world will stop coming up with new ideas when there’s no room for execution. Consider each team member’s history and their aspirations and, most importantly, *talk* to them about the kind of change you want to create to see how they react: are they excited, worried or indifferent?

If you’re trying to revive a stagnating team, a useful icebreaker may be to allocate time for intentional brainstorming and innovation. Try to put aside 20% or 10% of each iteration for the team to try their craziest ideas, and see how that pans out. This will give you time to get aligned on what innovation means to you, and how you want to go about it.

However, remember that this is still not ideal: “thinking time” is still you giving your team permission. Instead, you want to get to a point where they come to you spontaneously with their ideas, without waiting for you to tell them it’s okay to think. If you can get there and maintain that momentum, you’ll have a real Feedback-Centric Organization.

The Feedback-Centric Organization

Alberto Vena

Everyone keeps telling us to be gentle when reviewing Pull Requests, and that’s the right thing to do, but are we nice with who reviews ours?

A Pull Request is a way to communicate with other individuals who are responsible for the project’s maintenance, so we should do a good job improving our Pull Requests code and documentation to make their work straightforward. It’s also in our best interest to do that since the easier the review is the faster we’ll get our code merged.

## Who reads our Pull Requests?

Creating a reasonable Pull Request is a matter of walking in the shoes of people that will open it later, who fall into the following categories:

* **Code Owners**: who are in charge of reviewing and merging the code.

* **Developers implementing new features**: who are changing previously merged code and need to understand why that code is there.

* **Developers fixing bugs**: who encounter a bug and need to go deep in the git history to understand where the regression has been introduced and why.

We should be respectful of each of them while creating a Pull Request since facilitating their work both in the present and in the future is what makes software development honest and practical. “Time is running out” kind of excuses here are not valid, every moment that we don’t spend improving Pull Requests that we leave in our project is a lot of time wasted for who will interact with them later.

> A Pull Request is created one time but evaluated multiple times.

Do the math!

![](https://cdn.sanity.io/images/kqgmf0g2/production/61e451b8aa097487f4e8e20ab17f3ac713117f8c-560x240.gif?fit=clip)

## What reviewers dream to see

Let’s take a look together at what makes a Pull Request easy to review.

### Well organized code

Code is the soul of the Pull Request, but it won’t be my focus here. You can find a lot of resources about this on the Internet. I’ll only mention some general rules to apply code side:

* Make it small, try to break it into multiple Pull Requests.

* Write well-separated and well-documented commits, the why is the most important thing.

* Add tests, they’ll help reviewers understanding the context of the Pull Request.

* Take a look at the contribution guidelines usually at CONTRIBUTING.md; it may have important information.

### Meaningful title

It needs to clearly and exactly describe what has changed. For example:

![The preview of a wrong-formatter Pull-request title](https://cdn.sanity.io/images/kqgmf0g2/production/2c23d7ca307eba19629a23417b8c92525c59f42f-1340x200.png?fit=clip)
🔴 Bad: This one is too generic and doesn’t provide any value.

![The preview of a well-formatter Pull-request title](https://cdn.sanity.io/images/kqgmf0g2/production/e51f25dbd3166b9566efd0606c4f264866d63a64-1340x200.png?fit=clip)
✅ Good: This one is specific and explain what changed.

If you can only come up with a generic title, that’s probably a first signal that we could split the Pull Request into multiple ones.

A rule that I apply to determine if a title is good is to ask myself this:

> Could this title fit a CHANGELOG entry?

This soft-rule comes from my experience maintaining [Solidus](https://solidus.io/), the open-source project I mostly work on. On Solidus, before each release, we run a script that auto-generates entries for the CHANGELOG.md file using Pull Request’s titles. When they are self-explanatory, there’s much less manual work to do for maintainers.

### A description that really helps

Here’s the core of the Pull Request documentation. It’s quite common to assume that the Pull Request title and commits are enough for people to understand the context, but that’s not always true. For example, let’s consider this Pull Request title:

![](https://cdn.sanity.io/images/kqgmf0g2/production/2a55753537b7c1d02daf6a0746efd6d2e744bd47-1340x200.png?fit=clip)

I’m sure that when reading the Pull Request title today, with all the team focused on this specific change, everyone will immediately get what’s going on and **it could be tempting to leave the Pull Request’s description empty**. But what happens if you have to come back to this Pull Request in 1 year? Will you immediately remember how this switch has been done, and why?

Luckily, the “how” could still be read by commits description, even if it would be more time and energy-consuming to scan all the commits to get the sense of what’s happening. The real problem is that it’s tough to see the “why” of the change.

Let’s see what makes a good Pull Request description:

* It contains a **quick recap of the changes introduced**. It doesn’t have to be a lot of text, just something to quickly understand what changed without opening every single associated commit.

* It describes **why things changed**, try not to take for granted that the reader has a clear picture of the state of the system when the change happened. If the Pull Request comes from a change request done via an issues tracker, it could be handy to link that issue here.

* It describes the **steps to reproduce the changes introduced** with the Pull Request. It could be calling a method from a console, or make some interactions in a UI. It will drastically help reviewers to touch with hands the code they are seeing. It allows them to figure out any doubts that could arise in autonomy, without the need to ask for clarification and extra back and forth with the author.

* It includes **screenshots**: if the change has an impact on how the website looks or on any other visual part of the system, it’s a good idea to attach some screenshots. It will be super easy for those who look at the Pull Request to identify what changed and how.

With GitHub, you can guide the Pull Request author into providing all these things by using **Pull Request templates**. It’s a feature that allows to specify a template that will populate the Pull Request description for any new Pull Request. It’s just a matter of adding a markdown file into `.github/PULL_REQUEST_TEMPLATE.md`. Here’s a collection of [ready-to-grab Pull Request templates](https://github.com/stevemao/github-issue-templates) and the [GitHub documentation page for Pull Request Templates](https://help.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository).

There’s also another hidden, not well-documented GitHub feature, that allows having multiple templates for Pull Requests. You can get them by just reflecting this filesystem structure:

```
.github/
  - PULL_REQUEST_TEMPLATE.md .       # The Default Template
  - PULL_REQUEST_TEMPLATE/extra.md   # Additional templates
```

When you create the Pull Request, you can use the infrastructure template by adding the `&template=extra.md` in the URL’s query params.

### The right reviewers

The policy about asking specific persons to review our code could change depending on the project. For this reason, GitHub offers a [Code Owners](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) functionality that allows us to specify rules that automatically trigger review-requests from the right people. Here’s an example of a CODEOWNERS file:

```
*                   @project/backend-team
/app/javascript/    @project/frontend-team
/docs/              @project/documentation-team
```

This will ask for a review to the `project/backend-team` for all changes in the project excluding those that are located in `app/javascript` and docs, which will ask for a review to their respective teams.

I suggest integrating the usage of this feature with a clear team policy on how much time and how often developers are expected to review others’ code.

## Preview App linked to each Pull Request

Reviewers’ work is way smoother when they can test what a Pull Request changes before merging, and it’s a good practice to have a preview environment, very similar to staging, generated for each Pull Request open.

If you are deploying on Heroku, you can just use their [Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), whose setup is quite simple. It’s also possible to build something very similar by yourself: GitHub offers a Deployments API to create a Deployment section in the Pull Request page. By calling something like:

```
curl -X POST -H "Content-Type: application/json" \
-H "Accept: application/vnd.github.ant-man-preview+json" \
"https://api.github.com/repos/nebulab/project/deployments/42/statuses?access_token=XXX" \
-d '{ "state": "success", "environment_url": "https://your-custom-url/", "environment": "preview"'
```

You’ll see the deployment link in your Pull Request.

![The deployment button in GitHub](https://cdn.sanity.io/images/kqgmf0g2/production/bfe079861626b276e4e2cf4a47eb55f201bf93e7-1564x784.png?fit=clip)

At Nebulab, we use CircleCI and we’ve created a [CircleCI Orb](https://github.com/nebulab/circleci-orbs-feature-branch-preview) that allows us to have this functionality ready in minutes in all our projects by adding the following lines to the `.circleci/config.yml`:

```
version: 2.1

orbs:
  feature-branch: nebulab/feature-branch-preview

workflows:
  cool-workflow:
    jobs:
    - do-cool-things
    - run-specs
    - feature-branch/preview:
        domain: <domain-for-preview-apps>
        github_repo: <your-github-repository>
        github_token: <your-gh-auth-token>
        letsencrypt_email: <email-for-ssl-cert>
        server: <docker-server-to-run-containers>
        user: <docker-server-user>
```

### I bet you now want to be nice too!

After reading this post, you should! Being nice with reviewers gives you better and contextualized quality checks for your code, which should help you **grow as a developer**. It decreases **time-to-merge** for your code and will increases the **velocity to implement new features** that depend on existing ones. **Debugging is also faster** since you don’t have to read all the code to understand how and why a specific thing has been done. Helping reviewers means helping your team and your future self!

What Every Teammate Wants to See in Your Next Pull Request

During my career, I’ve had the honor of observing and being part of tens of engineering teams as a consultant, IC and manager.

Obviously, not all of these teams were equally effective at reaching their goals: some worked like perfect machines, others fell apart at every little problem, and most of them were somewhere in between these two extremes.

One would be tempted to explain these performance differences through a mere gap in technical skills — simply put, some people are more skilled than others and get more done, faster. The theory here is that the more highly-skilled engineers you hire, the better your team will perform.

This is certainly true, at least to an extent. However, if you talk to a seasoned manager, you’ll find that they’ve dealt with these two types of engineers at least once during their career:

* A junior engineer who absolutely crushed it not just from a technical perspective, but also in terms of the impact they had on the organization.

* A very senior and skilled engineer who never managed to accomplish anything meaningful, and ultimately moved on or had to be let go.

**Technical skill cannot always justify gaps in the performance of individuals or the teams they comprise**. There must be a more important underlying factor, one that justifies such dramatic differences in the impact people have on an organization, beyond their direct knowledge of the technologies and tools they work with. When present, this factor leads people to overcome their technical limitations in order to be effective at their job. When absent, it discourages them from pursuing meaningful results, no matter their skill.

Lately, I’ve come to realize the root factor may be **ownership**.

## An Intrinsic Trait with Extrinsic Results

Ownership is an intrinsic trait with extrinsic results: it’s born *inside* you, but most of the good things it leads to happen *outside* of you, in your interactions with others.

**Intrinsically, ownership is a sense of belonging and pride in one’s efforts that ultimately leads to the pursuit of excellence.** People who have ownership genuinely care about everything they do because they have the ability to see the value in it, even when it’s not obvious. Because of this love, they are willing to do the right thing.

**Extrinsically, ownership is the collection of traits that give managers peace of mind**: people who have ownership are dependable and consistent; they don’t wait for someone to assign work to them, but autonomously pick the thing that will have the most impact; they are in touch with the company’s mission; they work to the best of their abilities; they remove blockers from their way; they are not afraid to roll up their sleeves and fix something that’s broken, even when it’s not supposed to be their concern; they constantly re-evaluate and improve their way of working.

Most importantly, **ownership is contagious**, and it spreads very quickly: while technical skills take years or even decades to truly master, it only takes a few weeks of working in a team that consistently exhibits ownership for a new person to get up to speed on what’s expected of them. This is probably because we all have a natural sense of ownership and can recognize it and appreciate it in others when we see it.

## Ownership and Organization Design

In most mature organizations, there are at least three layers an individual is interacting with at any given time:

1. **The craft (the “how”).** When I am working, I am connected to the craft I am practicing to produce my work. An example is the relationship between an engineer and the code they write.

2. **The team (the “what”).** The code I write doesn’t exist in isolation (most likely), but is part of a larger endeavor my team is collectively working on. Together, we work on something bigger than ourselves.

3. **The company (the “why”).** Ideally, we don’t write code simply out of love for the code, but because we want to solve a problem we care about. Our company connects us all through its mission.

The three layers are also directly connected, and almost equivalent, to the three factors Daniel Pink identified in [Drive](https://www.amazon.com/Drive-Surprising-Truth-About-Motivates-ebook/dp/B004P1JDJO/ref=tmm_kin_swatch_0?_encoding=UTF8&qid=1587991379&sr=8-1):

* Ownership towards **the craft** corresponds to **Mastery**.

* Ownership towards **the team** corresponds to **Autonomy**.

* Ownership towards **the company** corresponds to **Purpose**.

In some organizations, ownership is experienced at all three layers: people love their craft, trust their team, and believe in their company. This perfect alignment creates the ideal environment for individuals to do their best work, and such an organization is bound to have an impact.

In other cases, there is a disconnection between these three layers. It’s important to note that, while the layers are connected to each other, the different levels of ownership people feel towards them may be completely independent of one another. Here are some examples:

* An organization whose members are deeply connected to the company’s mission, but completely uninterested in their craft.

* An organization that hires superstar employees by offering extremely generous compensation packages. In this case, employees will own their craft, but most likely not feel connected to the company.

* A dysfunctional organization that happens to have one or two very good teams in it. Their members are bound to feel a strong sense of ownership towards their team, but a very weak one towards their company (in extreme cases, people may favor their team while antagonizing their company).

Another important aspect is that the ways to foster ownership in these three layers are completely different. While ownership should be practiced first and foremost by the CEO, ultimately **it’s up to the individuals who comprise the organization to find the best ways to implement ownership in their work.**

Because the ways to foster ownership towards the company is largely independent of the type of company, and has been written about extensively already, and fostering ownership towards the craft is not something managers should be concerned with, let’s instead focus on how to foster ownership towards one’s team, especially in the context of an engineering organization.

## Ownership and Cycle Time in Engineering Teams

In a team setting, the biggest obstacle to team members’ ownership comes in the form of bottlenecks. Bottlenecks are steps of the work process that require team members to wait for someone before they are able to move forward with their work. **By removing responsibility from the person who is producing the work, they discourage that person from “owning” the work all the way to its completion.**

In the average engineering team, bottlenecks come in many different shapes:

* Software engineers need to wait for a PM to define the next sprint and assign work to them before they can start working.

* Software engineers need to wait for a QA engineer to test their work before their work is approved for deployment.

* Software engineers need to wait for a release manager to follow a very long and complicated checklist before their work gets deployed.

Every single bottleneck reduces the ownership individual team members feel towards their team: QA engineers find bugs in the features they test, but these bugs are never fixed and the work lingers in a limbo forever; engineers sit on their hands all day because they don’t know what they’re supposed to work on next. This results in a very tangible increase in cycle time.

Unfortunately, **engineering teams often don’t know a better way to do things**. In fact, many of them will argue that the bottlenecks are necessary: we need the engineers to have their priorities clear before they work, because the priorities change too quickly. We need to do manual QA on our system, because our system is too complex to rely on automated tests alone. We need to handle deployments with care, because the cost of a mistake is too high.

I would agree with all of these objections: there are products where the priorities would change dramatically from one day to the next, there are enterprise systems that are too complex for automated tests to catch all the permutations of interactions and edge cases that would cause a bug, and there are applications where the cost of a bad deployment can be computed by multiplying the minutes of downtime by a factor of one thousand or more.

And yet, I would never ever advise such teams to strip their engineers of their responsibility and ownership to protect the business — not because I think the sacrifice isn’t worth it, but because there is a better way. One that empowers teams and makes them more productive, resulting in more value for the organization and a better use of the engineering budget.

## A Practical Framework for Fostering Ownership

There are three activities paramount to building ownership in your team:

* **Communicate:** by communicating constantly with your team, you create alignment on the business priorities and expectations. Frequent and consistent communication gives your team the information they need to make decisions autonomously.

* **Streamline:** by streamlining processes, you empower everyone to follow them and make sure their work gets done. Note that streamlining doesn’t necessarily mean automating: while automating a process is the ultimate way to streamline it, proper documentation can also do wonders.

* **Trust:** ultimately, you need to trust your team to do the right thing. Most teams lack ownership because their managers don’t think their members can do the best interest of the organization without micromanagement. In the long-term, this lack of trust is a recipe for failure.

These three activities will take different shapes depending on the size and conformation of your team, but your end goal should always be to establish a framework for ownership and collaboration within the team. Everyone on your team should know not only what ownership means, but also how to exhibit it in their day-to-day work.

For example, here are some of the practices I have adopted over the years to foster ownership in the engineering teams I led:

* **Enforce direct communication:** when you’re a team lead, people have a tendency to go to you when they have a question, effectively turning you into a bottleneck and reducing their contact surface with the business. The next time someone approaches you with a question you can’t answer, encourage them to seek the answer by themselves. This may seem like you’re forfeiting responsibility, but what you’re actually doing is removing a bottleneck in the communication process.

* **Take “done” to the extreme:** most engineering teams don’t even have a definition of “done”, yet alone an extreme one. It should be clear that a feature is only finished once it’s been successfully deployed to production and used without problems by your users. Until then, the developer’s first priority should be to keep the feature moving through the development pipeline so that it gets done  — *actually* done.

* Turn **bottlenecks into leverage:** bottlenecks often come in the forms of individuals or teams who are responsible for keeping another team’s work moving forward. I’ve already made a couple of examples when I spoke about QA engineers and release managers. This kind of repetitive work alienates people and doesn’t add any value to your team — in fact, it slows them down. Instead, find ways to turn bottlenecks into leverage: the job of a QA engineer, for instance, should be to document QA processes and build tooling to automate them as much as possible. QA on individual features should be done by the engineer in charge of that feature.

* **Make ownership visual:** having a highly visual representation of the state of work can be extremely helpful in creating ownership. Most development teams work with Kanban boards, which are great for this sort of exercise: make sure your Kanban board actually has columns for every single step of your development process (e.g. don’t conflate code reviews with QA) and make it clear that it’s an engineer’s responsibility to keep things moving through that board at all costs. Also, make sure people give priority to things on the right (i.e. closer to get done) over things on the left. Having strict rules in place helps fight our tendency to start something new when we feel blocked on in-progress tasks.

* **Delegate decision-making:** nothing empowers people such as… their manager empowering them. Delegate decision-making as much as possible, even and especially when it feels a little uncomfortable. This doesn’t mean you should leave people to themselves: always be there for your engineers to talk a problem through, but give them the last word if possible. When someone has autonomy, they will honor that autonomy by exhibiting ownership.

As I said, your mileage may vary, but a good starting point is to try these practices in your team, keeping what works and adjusting what doesn’t. People will start taking ownership in ways that surprise you, identifying bottlenecks and creating original solutions to keep the process moving.

## Ownership Is a Gateway to Velocity

You have probably heard the term “velocity” before. A lot of articles talk about velocity and the difference between velocity and speed: while speed is just about how quickly you’re moving, velocity is also about *where you’re going*.

Many teams move crazy fast, but they often lack a clear direction. As a result, they do work that is not truly meaningful for the business, or they have to redo their work over and over again because of defects, incomplete implementations or missed requirements.

Once you and your team start exhibiting ownership, you will realize how connected ownership and velocity truly are: teams that own their work are teams that move both quickly and in the right direction. This connection exists for two reasons:

* **Ownership is first and foremost about doing the right thing.** Low-ownership environments discourage engineers from thinking about the business value behind their work, but high-ownership teams carefully consider each initiative and its impact from all possible angles. People will start doing things that really move the needle.

* **No one wants to own a half-done task.** Teams that don’t own their work often do the quickest thing that will allow them to cross an item off their list, whereas teams that exhibit high levels of ownership know that the work doesn’t stop when it’s in production: quick and dirty solutions mean more maintenance work down the line and less time for high-impact initiatives.

As you can see, creating a high-ownership environment is not just the best thing you can do for your team members, but it’s also the best thing you can do for your business: it will increase the volume, quality and business impact of the work produced by your engineering team.

For a lot of managers, it can feel scary to give away control so radically, once you have seen the results, you’ll never want to go back.

The Transformative Nature of Ownership in Engineering Orgs

One of the most important decisions you will make when launching your digital brand is which eCommerce platform you build your store with. Typically, there are three categories to choose from:

* **SaaS platforms** are online software solutions that handle all the complexity of building and running a store. In exchange for a recurring license fee, these tools provide a storefront your customers can access as well as a backend to to manage your store. They are by far the quickest and easiest solution to get started. Popular examples in this category are [Shopify](https://www.shopify.com/) and [BigCommerce](https://www.bigcommerce.com/).

* **Open-source platforms** are ready-made software packages that provide similar functionality to what you could get with a SaaS platform. Because they are open-source, these platforms can be customized, although many of them are not built for that. Furthermore, you have to host them in your own infrastructure. Popular examples are [WooCommerce](http://woocommerce.com/) and [Prestashop](https://www.prestashop.com/).

* **Open-source frameworks** are software solutions that provide the basic functionality you need to build your store. They vary in functionality and underlying technology, but most of them are built to create extremely custom experiences and provide a very high degree of flexibility, at the cost of a steeper learning curve and a larger upfront investment. Popular examples are [Solidus](https://solidus.io/) and [Saleor](https://saleor.io/).
The main difference between SaaS platforms and open-source platforms is the pricing model: SaaS platforms require paying a recurring license fees, while most open-source platforms are free. In terms of functionality, however, they are pretty similar, so we will instead focus on the differences between SaaS platforms and open-source frameworks.

## Cost of ownership

SaaS platforms have two main pricing models: you either pay a fixed fee every month/year, or a percentage of your store’s sales volume. This results in a pricing model that scales with your store, but **it also means you are paying money just to keep your store online instead of investing in its continuous evolution.**

Most open-source frameworks, on the other hand, are entirely free to use, but you need to hire a development team that will build, launch and maintain your store. While this model requires a larger upfront investment, **it’s also a better fit for those entrepreneurs who are serious about investing in the technology that powers their business.**

If you can afford a larger upfront investment and you expect your brand to scale seriously, going with an open-source framework will reduce your total cost of ownership while creating more opportunities than you could get with an off-the-shelf solution.

## Customization possibilities

SaaS platforms offer a great starting experience with no customization work needed. This is really helpful for people who are just getting their feet wet in the eCommerce industry: **if you don’t know how to create a good UX and just want to start selling, a SaaS solution will help you.** This kind of simplicity doesn’t come for free, though: **SaaS platforms are not always easy to customize, and in certain cases you are stuck with the default experience they provide.**

Going with an open-source framework means you’ll have to figure out more stuff by yourself, but **it also affords you the flexibility to customize each and every aspect of your store however you see fit,** allowing you to truly innovate the buying experience rather than being one more droplet in a sea of digital brands.

The most prominent online brands became memorable not just because of their products, but because of the experience they created around all brand interactions. **If eCommerce is an important channel for you, you need to start seeing yourself as an experience company,** and treat technology as a first-class citizen.

## Data ownership

**SaaS platforms, unfortunately, act by their very nature as middlemen between you and your customers.** Because you are not hosting your infrastructure when you adopt a SaaS solution, you lose direct access to a lot of potentially useful information. These platforms try to make up for the lack of data ownership by providing out-of-the-box reporting tools, but they often fall short of brand expectations.

**With an open-source framework, you will always have complete access to all the data generated by your store.** This data can be used in any way you see fit: you can either customize your platform to generate advanced reports internally, or connect an external business intelligence tool that will help you take full advantage of all the information at your disposal.

Being a digital brands allows you to use data to your advantage: by accessing information that is not always available to traditional brick-and-mortar retailers, you can make smarter decisions, which reduces your costs and helps you stay competitive. The paradox here is that **data ownership is even more important for smaller brands, which don’t have access to economies of scale and can afford fewer mistakes.**

## Time to market

Because most SaaS solutions provide all the tools you need to start an online business out of the box, it will always be quicker to get your brand started with a SaaS platform than with an open-source framework, at least for a basic store. **If you’re in a hurry to get started and cannot afford to wait, you should definitely look into SaaS.**

With that said, one aspect to keep in consideration is the velocity of your team when evolving your store in response to market conditions. **In the hands of a skilled engineering team, an eCommerce framework will be not only quicker to adapt, but because it’s built to be customized, it will also allow you to make optimizations that stand the test of time.** SaaS platforms, on the other hand, often require ugly hacks that cost you more time in ongoing maintenance than for their initial development.

For most brands, time to market for the initial launch is not a relevant factor. On the other hand, time to market in capitalizing new opportunities and evolving your eCommerce experience can make or break a digital brand.

## So… which one is it?

As you have seen, there are different factors to take into consideration when choosing the best eCommerce platform for your needs. Most of them boil down to two key aspects: experience and vision.

**If you are only getting started in eCommerce, or think of your brand mainly as a product company, you should probably consider SaaS options.** They will make selling online a no-brainer, at the cost of technical limitations and a higher total cost of ownership.

**If you are an eCommerce veteran, or consider customer experience to be paramount in building your brand, you should instead going with an open-source framework**, making a larger upfront investment in order to have a flexible platform that will allow you to deliver a completely custom experience.

What Can Open Source Do for eCommerce?

As an eCommerce consulting firm, we know the value behind a custom store implementation: **not going
with a SaaS solution affords you maximum flexibility and endless innovation opportunities** —
there's nothing a good development team can't do.

For digital brands, this can be powerful: **when your platform doesn't limit you, you can implement
whatever you have in mind,** and create even stronger bonds with your customers.

However, there are also downsides:

* Having a solid development workflow is good for new features and invasive modifications, but it
  becomes a bottleneck when you only need to change an email template, or the arrangement of
  elements on a page. Relying on developers for these tasks can slow you down.
* **Your developers' time is important and, most likely, expensive.** Having them make trivial
  adjustments to your content or campaigns may not be the best use of their expertise. Instead, you
  should do whatever you can to free them up for more important work.

Luckily, a lot of tools have emerged over the last years that allow you to make changes to almost
every customer-facing aspect of your store without necessarily involving your developers. These are
SaaS tools that only have to be integrated with your store once, and then provide you with an admin
panel you can access and use autonomously.

There are a lot of options for different categories, and over the years we've used many of them for
our customers. Here's a round-up of the best one in each category, along with a few alternatives
you may also want to try!

## 1. Manage your content yourself

Content management is one of those areas where self-serve tools have been available for a long time,
but are not always used (the right way). Headless CMS solutions are all the rage now, and the
philosophy behind them is fairly simple.

Unlike a traditional CMS, that allows editors to enter whatever they want in the page, with the risk
of creating un-optimized or even broken layouts, **headless CMSs require your developers to specify
the possible structure of the content upfront.** Content editors can then manage the content through
the headless CMS. Finally, this content is pulled by your store and displayed to your customers when
they visit the corresponding page(s).

While they may seem limiting to someone accustomed to old-style content management tools, **headless
CMSs are extremely powerful if used the right way**, and they can be just as flexible, if not more,
than traditional solutions, while sparing your developers a lot of tedious work.

### The best headless CMS: Prismic

[VIDEO](https://drive.google.com/file/d/181Oppz0QeRmrr11ShCrQ4DXC4jwpTNQT/view?usp=share_link)

Out of all the headless CMSs we have tried, [Prismic](https://prismic.io) definitely comes out on
top. **It's an extremely modern tool with a powerful API and development toolkits for the most
popular languages, and it can be easily integrated in any application.**

Its pricing is also [very competitive](https://prismic.io/pricing), with a free basic plan and
attractive options for organizations of all shapes and sizes.

There are a couple of alternatives also worth considering:

* [Alchemy CMS](https://alchemy-cms.com/about) is an open-source, self-hosted headless CMS for Ruby
  on Rails applications. It's a good option if you don't want to pay a third-party to host your
  content, but may be more complex for your development team to configure and maintain, especially
  if they don't have experience with Ruby.
* [Contentful](https://www.contentful.com) is Prismic's main competitor. While it's a solid option
  trusted by large companies such as Spotify, Lyft and Twilio, we have found it to be less reliable
  than Prismic, and a bit behind the curve when it comes to its technical capabilities. The pricing
  is also [much steeper](https://www.contentful.com/pricing) than Prismic's, going from $39/mo to
  $879/mo.

## 2. Build 360-degree marketing campaigns

**For digital brands, creating a loyal customer-base that identifies with your values and mission is
a matter of life or death**, and how, when and where you communicate with your users is key to
creating a successful and engaged community of brand _aficionados_.

Unfortunately, very often these touchpoints are hardcoded by developers into the application, which
means every experiment and every change need to go through the development team before customers can
benefit from them. **This can be especially critical for time-sensitive marketing campaigns,** where
getting the timing right can mean the difference between a customer and a lost sale.

Luckily, there are a few tools out there that can help you take back control. The integration flow
is usually straightforward: you ask your developers to send customer information to the marketing
automation service, which you then use to communicate with customers autonomously.

### The best marketing tool: Klaviyo

![The Klaviyo email marketing UI.](https://cdn.sanity.io/images/kqgmf0g2/production/34c56d7e6b8d6bda3f2dfaf44a6668137211eab0-1395x762.png?fit=clip)

A relatively recent product, [Klaviyo](https://www.klaviyo.com/) won our hearts when we first used
it, thanks to its flexibility and ease of customization for the end-user.

It allows you to run email, SMS and social media marketing campaigns all from the same interface
and leveraging the same dataset, and (obviously) supports A/B testing of your campaigns so that you
can test small changes and tweak your campaigns accordingly.

But where Klaviyo really shines is in its event-based architecture: by integrating with your store,
**Klaviyo knows when your customers take certain actions and allows you to build complex automated
campaigns** such as abandoned cart flows, all without having to involve your devs!

The most prominent alternative to Klaviyo is [Mailchimp](https://mailchimp.com), a giant in this
industry. While it provides many of Klaviyo's features, Mailchimp lacks SMS marketing capabilities
and has other features, such as landing pages and postcards, that may not be needed by the average
brand.

## 3. A/B test to your heart's desire

A/B testing can be a complex feat to pull off properly. Not only do you have to implement the
testing logic, but you also need a solid framework in place to validate the results of your
experiments and ensure you're not jumping to conclusions.

From a technical standpoint, implementing experiments is not fun either: each experiment needs to
be implemented manually, and failed experiments often linger unused in your codebase because no one
has time to remove them. **Over time, this accumulation of failed experiments can create huge
amounts of technical debt and slow down development.**

The complexity behind running a reliable A/B test often puts off companies who'd like to start with
the technique. When done right though, **A/B testing can be a powerful tool to optimize your
conversion rates and get a better sense of your customers' taste**, and there are a few tools you
can use to make this process a breeze.

### The best A/B testing tool: Optimizely

![The Optimizely A/B testing UI.](https://cdn.sanity.io/images/kqgmf0g2/production/1c7ac7dc278e63f43c8fd68b6f1cf66dd6f6101b-1849x1278.png?fit=clip)

[Optimizely](https://www.optimizely.com/) is an all-in-one platform for A/B testing all aspects of
your website, trusted by the most prominent startups and enterprises. A full-stack implementation
consists of two components:

* A frontend plugin that allows you to **run customer-facing A/B tests without involving your
  development team**, e.g. testing two versions of your landing page.
* A backend integration that allows your development team to implement A/B tests for more complex
  aspects, such as testing different promotions or shipping options.

You can manage experiments directly from Optimizely's UI, **which will also determine the winner
with its proprietary algorithms** — no Excel spreadsheet needed.

A popular alternative to Optimizely is [LaunchDarkly](https://launchdarkly.com), although you should
know LaunchDarkly is more focused on feature flags and does not provide a visual editor that allows
you to run customer-facing experiments without asking your developers.

## 4. Up your data collection game

Data is the stepping stone in the journey from online store to digitally-native vertical brand. As
Andy Dunn, one of Bonobos' co-founders and
[the man who coined the term _DNVB_](https://medium.com/@dunn/digitally-native-vertical-brands-b26a26f2cf83),
says:

> Deeper data on the consumer drives enables the DNVB to stay closer to the customer than its brick
> and mortar driven peers, and the ownership of the brand end-to-end fuels more affinity for a
> vertical commerce brand than even the best e-commerce experiences.
Being able to do more with your data unlocks new possibilities for your business. In turn, **your
ability to analyze data in a meaningful way is a function of how much data you collect and where.**

Traditionally, adding a new analytics service to your toolbelt has been very dependent on
development work. Developers would have to write a custom integration for the new service and then
test it to make sure data was being collected consistently and reliably. This could result in slow
integration times and lost opportunities.

But in the last few years, a new category tools was born that promise to solve this problem once
and for all. This new breed of services acts as a gateway between your application and all of your
tracking and analytics tools. They provides a unified programming interface that **drastically
simplifies the integration work for your development team,** as they only have to integrate with one
service and not ten. Store owners can then manage all of their tracking integrations from the
gateway's control panel. Adding new services is as simple as clicking a button — no dev needed!

### The best data platform: Segment

![The Segment data collection UI.](https://cdn.sanity.io/images/kqgmf0g2/production/0f94ab549ae2c13cf121a0c26936e899aa9f079d-1121x519.svg?fit=clip)

[Segment](https://segment.com) touts itself as a customer data platform (CDP). In other words, they
provide a centralized data collection service and give you the tools you need to manage and act on
your data.

Trusted by tens of startups and large organizations, Segment lives up to its promise of dramatically
simplifying data collection: **developers only have to integrate Segment in your application once.**
You can then enable and test new tracking and analytics services in a blink of an eye, freeing up
your engineering team's time for other initiatives.

In our experience, **Segment is incredibly reliable and provides an amazing user experience.** It
reduces development spend and implementation time.

A popular alternative is [Google Tag Manager](https://tagmanager.google.com/), which allows you to
manage all of your tracking snippets from one interface. However, GTM is much more limited than
Segment, because it simply acts as a central repository for different tracking codes, and doesn't
know anything about the data you are collecting. On the upside, it's free, so it may be a good
starting point if you just want to dip your toes in this water, or if you don't need a full-fledged
data collection platform.

## 5. ...and access new business insights!

Now that customer data is flowing in the right direction(s), it's time to use it to make informed
decisions about your business. In order to do that, many stores develop their internal reporting
tools, which take a lot of time away from core business priorities, or turn to Excel spreadsheets,
which often fall short of business requirements.

Instead, **companies that use data to drive important decisions, such as digitally-native vertical
brands, can and should rely on battle-tested Business Intelligence (BI) platforms.** These are tools
that plug directly into your data sources and can generate reports about all aspects of your
company's operations and sales.

Using a BI platform instead of in-house solutions allows you to access richer insights into your
data and let your developers focusing on core business capabilities rather than internal software.

### The best BI platform: Looker

![The Looker business intelligence UI.](https://cdn.sanity.io/images/kqgmf0g2/production/ad302d86b3f6a04f0641560e3f0bcdc04966649d-942x571.png?fit=clip)

There's no shortage of BI platforms, as these tools have always been used by companies of all sizes
to better understand the market and drive strategic decisions. Among all the options,
[Looker](https://looker.com) stands apart for its modern take on business intelligence.

By combining BI, data visualization and reporting capabilities, **Looker allows you to create very
flexible experiences:** for instance, you can embed data visualizations directly in your store's
dashboard, or send a sales report every month to your key decision-makers, so that everyone's always
in the loop and can make the right decisions.

**Looker allows you to access the data you need, wherever you need it,** making sure that reports
are being put to good use rather than just sitting there and gathering dust.

[Tableau](https://www.tableau.com) is also worth looking into, although it takes a more traditional
approach to business intelligence, centralizing all your data and reports under the same roof.

## Flexibility + automation FTW

Most of these tools have plugins to integrate with the most popular SaaS eCommerce platforms.
Unfortunately, **these plugins often offer a shallow integration** that doesn't cover all customer
touchpoints or doesn't capture all the data you could leverage.

In some cases, the fault lies on the plugin developer for not doing a good job. In others, it's due
to the sandboxed nature of SaaS solutions, that don't expose all the hooks and information the
services need to show their full potential.

**By adopting a flexible, open-source eCommerce framework such as [Solidus](https://solidus.io), you
are getting the best of both worlds:** on one hand, you can create deep integrations that let you
leverage all the features of these awesome services; on the other, you are not limited by your
platform, and can implement all those features that make your brand stand apart from its
competitors.

5 No-Code eCommerce Management Tools

Matteo Latini

These days code is a collaborative matter. Good developers are expected
to both write great code and help others write code. Code reviews play a crucial part in this: they're the main tool a team has to ship great code and have fun while doing so.

## 😤 Reviews are hard

First of all, let me say it loud and clear: doing code reviews is **damn hard**.
If somebody says giving a pull request review is easy it's probably because they never actually went over a pull request. Pull request reviews are hard because:

* you need to be polite and forgiving;
* it happens remotely 99% of the times;
* you need to think like someone else;
* everyone has their own coding style and it should be respected;
* code written in 10 hours is often reviewed in under 10 minutes;
* praise and criticism happens publicly;
* you are going to write stupid things and completely fail;
* ...

It also depends on the PR of course: certain PRs are pretty straightforward.
You can relax with simple PRs, just approve them and merge them ASAP, your
code deserves it.

I think you get the picture: pull request reviews are more about people and less
about code and computers. In a productive development team reviews should happen
often and be stress-free; they should help the team improve over time, spread
knowledge and increase overall badassery.

## 📕 My Checklist

When I need to go over a pull request I do it several times and use each time a
different point of view. I do this because checking everything at once is simply
unbearable... I lose track of what I'm looking for and I need to start all over
again. So each time I need to look at a PR I look for:

1. syntactic correctness
2. feature completeness
3. meaningful use of git

### ✅ Syntactic Correctness

This is the first check: it's easy and fast (depending on the amount of code)
and doesn't require a fresh brain and, usually, can even happen late during the
day because it's just a matter of checking:

- do tests pass? Is the build green?
- does static code analysis report problems (i.e. [RuboCop][rubocop] and
friends)?
- overall look of the code, are there any code smells?
- are the description and the commit messages written in proper English?
- does the PR respect all of the project conventions (i.e. branch naming,
labels, ...)?

Generally, if something is clearly wrong I either assume the PR is not ready to
be reviewed or straight away ask for a fix on those simple things before digging
into the PR.

The key take-away here is **automation**: you'll save a ton of time by using
tools like [overcommit][overcommit] or [Hound][hound], take the time to
configure them properly so they can do the work you would do manually.

Another thing I do regularly is using [pull request templates][pr-templates] to
add a checklist of what a project needs. Depending on the project and team, stating
clearly the review process within the PR itself can be a huge time-saver,
especially for simple requirements. There are a [ton of examples][pr-template-examples]
you can choose from.

![](https://cdn.sanity.io/images/kqgmf0g2/production/a30b68397c4da12a3e1274e08ff86159eff9e1fa-200x144.webp?fit=clip)

### ✅ Feature Completeness

This step is the hardest. First of all, I read once or twice the issue the PR is
trying to solve (it should be linked in the PR description), then I go over the
code changes, class by class, file by file and dig down the code as in depth as
I can.

The idea here is to try to understand if the person that wrote the code:

- had a good understanding of the issue (asked the right questions, had the
required skills, ...)
- wrote code that actually solved the issue
- didn't miss any edge-cases
- used the right design patterns (and didn't over-engineer the code)

All of the above can be *extremely hard* because you're generally looking at
the result of several hours of work in a short amount of time (sometimes you even
need that code in production and it won't help).

The key takeaway here is **open-mindedness**: never assume anything. Always be
neutral when reviewing code, you should look at code as something that can
advance a project, not like a form of art.

If you've been asked for a review there's a good chance you're the more senior
developer (at least in that competence area). It can be tempting to request
changes just because the code "looks ugly" or maybe because that doesn't look
like something you would write... That's not the way you should do it: look for
real problems, effective solutions and give developers the freedom to write the
code in their style within the project guidelines.

![](https://cdn.sanity.io/images/kqgmf0g2/production/eacaebf6b0ca46c088f79d4baeef17bc69419e5a-499x341.gif?fit=clip)

### ✅ Meaningful Use of Git

So, the code looks solid, now onto the commits. Why are commits so important?
I think of the git history as a ball of yarn that needs to be untangled: would you
prefer the thread to be neatly rolled around... or would you prefer it to be randomly
put together just for the sake of building a ball form?

This makes sense to me because we've always used [Trunk Based Development][trunk] so
our projects' `master` history is a single line of commits with each commit connecting
(hopefully) to the following one, in a single stream of changes. As the features grow and
evolve, the git history linearly represents what happened and why.

With commits following one another it's helpful to try to tell a story with [good git
messages][git-messages] and overall common sense. I ask for changes on a PR when:

- meaningless history added (code is added and removed within the same PR)
- lots of changes and few commits (history is not explained properly)
- lots of commits and few changes (meaningless history probably added)
- commits explaining what the code does instead of saying why it does it
- merge commits (rebasing is a tidier way of making changes on PRs)
- commits not explaining what's happening (the infamous "fix the fix")

A lot of my time goes into reviewing git messages and it can sometimes feel like a
chore (in particular for smaller projects) nonetheless understanding clearly
what and why a particular piece of code is there is crucial for long term success
of a team of developers. On long term projects developers often forget what happened
a year ago, not to speak of new developers picking up the project later down the road.

![](https://cdn.sanity.io/images/kqgmf0g2/production/528c59f74aa0bd3b3a7ab8c1f93c258813f22db0-392x208.gif?fit=clip)

##  💅 Tips and Tricks

And that's pretty much it! I'll end this post with a final list of random things
that I find helpful:

* automate everything that can be automated
* giving reviews will help you write reviewer-friendly code, encourage everyone to review code
* speak to your team so that they know you don't hate them
* practice [Radical Candor][radical-candor]
* add gifs and funny pictures once in while to a review, a good laugh will set the right mood
* you're not on Twitter, don't troll around
* always explain why, never say "change this" without actually providing some examples
* if everything else fails, schedule a pairing session
* schedule your "review time" (I generally do 80% code/20% reviews)

A Guide to Effective Pull Request Reviews

Once the number of decision-makers in a company increases, it becomes increasingly more difficult to
gather feedback and get stakeholder buy-in on organization-wide changes and policies.

Conference calls and instant messaging, the two communication mediums of choice at most modern
companies, are not the right tool for the job: their fast-paced nature and volatility makes it
difficult for people to collect and organize their thoughts before sending them out to their
colleagues for evaluation.

## Feedback takes time

For most of us, it takes hours or even days to analyze a new idea from all possible angles and
structure it properly, but in a chat or a call, you only have minutes to do it before losing
people’s attention. This makes these tools the perfect place for quick back and forth, but not a
good choice for decisions or projects with a wider scope.

The same goes for feedback: **if you really want someone's opinion on your plan, you need to give
them time to think it through.** You are not going to have someone’s full attention by Slack-ing
them in the middle of the morning - the best you can hope for is a thumbs-up. It gets even worse
when people are sick or on vacation: in this case, you risk completely missing out on their feedback
because they were simply not in the right place at the right time.

At Nebulab, we started experiencing a few of these problems and then some more. With four directors
handling all aspects of the company’s operations and a marketing and design department to coordinate
with, we started experiencing a lot of frustration when trying to propose new initiatives that
affected the entire company.

Furthermore, people would be too busy to leave their feedback on new ideas or simply miss them in
the daily sea of Slack messages. When left, feedback would then sometimes be misplaced and/or
forgotten, which caused a lot of friction and slowed down the implementation of new initiatives.

We knew there _had_ to be a better way to discuss ideas and make decisions. We just didn’t expect it
would come all the way from 1969.

## Enter the world of RFCs

The Internet has had a structured format for gathering feedback and describing initiatives for quite
a long time: in 1969, Steve Connor wrote the very first RFC (Request for Comments) at UCLA to
organize the work of the new ARPAnet research program. In fact, RFCs were the first online
publication series.

Over the years, RFCs have been used as a way to gather peer review on new ideas, architectures and
protocols by many official bodies and independent authors all over the world. While some RFCs end up
becoming Internet standards, for the vast majority of them the purpose is to gather initial feedback
on an idea to refine it and make it ready for real-world usage.

We thought RFCs would be the perfect format to propose new ideas and initiatives in Nebulab.

## Our RFC template

We knew we’d need to tweak the format slightly: RFCs used by the IETF tend to be very formal,
because they describe standards that will be potentially adopted by the entire Internet, but in our
case we just wanted to propose changes for our company.

With this goal in mind, we listed a few constraints for our RFCs:

* They had to allow us to **explain an idea in detail** and reply to reasonable objections in
  advance rather than on the spot.
* They had to provide us with a **centralized place to gather peer feedback** and implement it
  before being rolled out.
* They had to provide **a clear framework for experimenting** with new ideas before making them
  official company policies.

We quickly sketched a first draft of our RFC template in Google Docs. We chose Google Docs because
it makes it extremely easy to organize files, share them with the right people and gather and
implement feedback in the form of inline comments.

This is what we came up with:

![](https://cdn.sanity.io/images/kqgmf0g2/production/1c6b4aade8b264af3c9ff37d121b518e9d0de0b3-1278x1526.png?fit=clip)

I’ll skip the header, since it’s quite self-explanatory. Instead, let’s walk through the other
sections one at a time.

## Why, what, how

First of all, we want to explain _why_ we are proposing this change. This really forces us to think
about the problem we’re trying to solve and the outcome we want to achieve. This is probably the
most important part of the entire RFC: **the best-designed initiative in the world won’t do your
company much good if it’s solving the wrong problem**, and putting it in writing helps you ensure
you deeply understand the challenge at hand.

Next, we explain the solution we are proposing to the problem. These are the implementation details,
and we usually go quite in depth here about what we want to do and how we plan to do it. This allows
peers to visualize our solution and provide feedback to propose improvements and better alternatives
to our plan, as well as to find any drawbacks or areas of the company that we forgot to cover.

Finally, we describe the roll-out plan for our initiative. When you start with a brand new policy or
project, it’s not enough to simply dive into the execution. Instead, **you need to create the proper
structure to support your initiative**, communicate it to the relevant team members and ensure
everyone’s on board and clear on how to execute. We quickly realized that this initial phase can
make or break our ideas, so it can’t be left to chance.

The first three sections give you a pretty good overview of the problem we’re solving and how we
want to solve it, but how can we go about validating our solution?

## Define what success looks like

This is where the _Metrics_ section comes in. For each RFC, we do our best to list two or three
metrics that we can use to evaluate the proposal and determine whether it’s working as expected or
not.

This is necessary because it’s very easy for new ideas to start accumulating on people’s plates and
drag on even when it’s clear they aren’t working. No one wants to shoot an idea in the head,
especially when it’s not ours, but **every new policy and every new initiative come with a burden:**
management needs to document it and team members need to understand it and execute on it.

By having clear metrics, we can revisit an RFC and quickly determine if it solved the problem it was
designed for or not.

This is what we use the _Status_ column for: when an RFC is first created, it’s a _Draft_. Then,
once it’s ready to be shared with relevant team members, it becomes a _Proposal_. At this point, any
feedback is integrated and the RFC is finalized and rolled, and it becomes _Experimental_. When we
revisit the RFC and determine whether it’s working or not, it becomes either _Effective_ or
_Abandoned_.

## Plan for the future

You may have noticed the template also has a _Future possibilities_ section. This is because we
encourage people to keep their initial RFC for an initiative as lean as possible, which allows them
to quickly validate ideas before deciding whether to continue with their development or not.

So, for instance, for an RFC that describes a new type of service Nebulab could offer to its
clients, future possibilities may include productizing that service so that we can provide the same
value to clients with a fraction of the work. However, this is definitely not something we want to
do in the initial phase of the implementation, since it would cost us a lot of time before we even
know if the service resonates with our customers.

By planning for future possibilities in advance, you can write down any ideas while they’re still
fresh in your mind without spending the time to implement them.

## Asking for and integrating feedback

As I mentioned, one of the reasons we chose Google Docs is because it makes it extremely easy to
leave inline feedback on a document, and the comments system allows the author of the document to
reply to the feedback, reach a conclusion and incorporate it in the original content (or drop it).

When we’re working on an RFC, we usually ask for **30% feedback, 60% feedback and 90% feedback** so
that we can adjust the document at different stages of its lifecycle. This concept is better
explained in <a href="https://blog.trello.com/avoid-the-seagull-effect-30/60/90-feedback-framework" target="_blank">an
article by Trello</a> which we strongly invite you to read. It can be applied to all kinds of
feedback, not just RFCs, and **it can truly transform how a company thinks about feedback and
collaboration.**

In the case of an RFC, an important aspect to keep in mind is that, because of their experimental
nature, the author(s) have complete freedom on which feedback to accept and which to discard. Your
RFC is your baby and you can decide how you want to raise it - after all, that’s why we have a
structured way to determine success!

## When NOT to use RFCs

I want to end on a note of caution: RFCs can be a great tool for driving change across a company. As
we’ve seen, they give us a structured way to document a transformation, get buy-in from teammates
and evaluate the results. However, they’re not a one-size-fits-all tool, and there are a few
scenarios where I’d advise against using an RFC:

* **When the change is so small it doesn’t warrant a full-blown discussion.** This can be the case
  for instance with small implementation changes for existing initiatives. At the end of the day,
  you set this boundary, but make sure to use your judgment.
* **When the change has limited scope (i.e. it only affects a team of the company).** In this case,
  you’re probably better off discussing the change with the individuals involved directly rather
  than trying to capture all the details in advance.
* **When you don’t actually care about the feedback.** We strongly encourage people to own their
  aspects of the business here at Nebulab and we give them all the freedom they need to do it. If
  you feel very strongly about a choice and you can validate it easily and with little to no
  repercussions, then just go for it.

As always, your mileage may vary, but we’re pretty sure most companies could benefit immensely from
having a more structured approach to organizational change.

## Additional resources

The following articles have been a source of inspiration for our RFC process and we strongly
recommend them:

* [https://philcalcado.com/2018/11/19/a_structured_rfc_process.html] A Structured RFC Process
* [https://blog.trello.com/avoid-the-seagull-effect-30/60/90-feedback-framework] Avoid The Seagull Effect: The 30/60/90 Framework For Feedback

Finally, [https://docs.google.com/document/d/1cSNTB0ECzyiuTMm2Rb8RiGtN_iizzmjWJZiztljTv4w/edit"] (we
have published our RFC template), so that you can easily fork it and use it at your company!

Using RFCs to Drive Organizational Change

Georgy Shabunin

## Motivation

At the very beginning, HTML was among the first and few technologies enabling
creation of web documents. Not long, JavaScript was introduced, sprinkled here
and there, drop-down menus and simple animations started to appear. Eventually,
the web advanced from simple static websites to highly-interactive asynchronous
web pages.

The web has evolved and so did [Ruby on Rails](https://rubyonrails.org/). The
framework now provides improved JavaScript tooling, including integrations for
both [yarn](https://yarnpkg.com/en/) package manager and [webpack](https://webpack.js.org/) module bundler -
de facto choice in the JavaScript community. Out of the box support for these tools
facilitates creation of rich client applications. We can now easier than ever build
Rails-backed applications with modern tools like [Vue](https://vuejs.org/), [React](https://reactjs.org/) and [Angular](https://angular.io/).

However, as we develop our applications with modern JavaScript libraries, a new
concern emerges. Feature specs that once brought confidence are now becoming
increasingly brittle. Specs that once steadily navigated through almost static web
pages now stumble and fall in an asynchronous world of JavaScript.

Hence, similarly to how webpack and yarn were previously introduced to *build*
modern applications, we further introduce [Cypress](https://www.cypress.io/) to *test* them. Particularly,
in this post, we look at Cypress as an alternative tool for writing and executing
feature specs. We explore the key points that make it stand out among other web
automation tools. Finally, we demonstrate how to integrate Cypress into a Ruby on Rails
development cycle by setting up tests in both local and CI environments.

## Cypress

Cypress is a JavaScript end-to-end testing framework. It is an all-in-one solution
that enables one to both write and execute tests that run in the browser. In a
Rails project, Cypress takes place of both Capybara and the underlying web driver.

## Cypress vs Selenium

Without doubt, Capybara is the most popular and widely adopted solution for integration
testing in Rails. It provides a robust interface to communicate with the browser
through a web driver. Although Capybara is agnostic of the installed driver,
[Selenium WebDriver](https://github.com/teamcapybara/capybara#selenium) is the prevailing choice among Rails developers.
As Selenium is the most widespread solution also beyond Rails, it is therefore important
to understand the difference between Cypress and the combination of Capybara/Selenium.

The key difference between Cypress and Selenium lies in their ways of communication
with the browser, i.e. browser automation. With Selenium, all communications are
done through an external to the browser driver (the WebDriver). To simulate user
actions, Selenium queries the browser by sending remote calls through the network and
then extracting the desired information from the responses. Cypress, on the other
hand, doesn't involve any network communication. It lives directly in the browser
and runs the tests in the same run-loop as the client application. That is, Cypress
tests are right there - in the browser, sharing the same context with your application.

As an outside process, Selenium is not able to react to events in the same run-loop.
Events are thus processed asynchronously, can be overlooked and network delays may
be introduced. This may lead to test flakiness and longer execution times.

In contrast, by sharing the same JavaScript event-loop with your application, Cypress
is synchronously notified of all events as they occur leading to more reliable test
execution. Removing the network layer allows Cypress to execute tests as fast as
the browser is capable of rendering.

The browser-integrated architecture of Cypress accounts for it's quick and reliable
test execution. Sounds promising. But let's see it for ourselves. Next move: install
Cypress in a Rails project. You can find the source code for the demo project [here](https://github.com/nebulab/cypress-store).

## Cypress on Rails: hands-on experience

### Application setup

We want to quickly bootstrap a Rails application with some logic, data, and views
already in place so that we can focus on the testing part. A fresh installation
of [Solidus](https://github.com/solidusio/solidus) will do the job. Solidus is a
highly customizable ecommerce platform.  By adding Solidus gem to our project we
get a default store implementation right out of the box. Bellow is an outline of
all required application setup steps:

1. Create a new Rails project, use [Postgresql](https://www.postgresql.org/) for the database and skip the test files:

```bash
$ rails new cypress-store -d postgresql -T
```

2. Add Solidus to the project by installing two new gems and running their
included generators:

```ruby
# Gemfile

gem 'solidus'
gem 'solidus_auth_devise'
```
```bash
bundle exec rails g spree:install
bundle exec rails g solidus:auth:install
bundle exec rake railties:install:migrations
```

3. Run the rails server and navigate to the index page, you should be greeted with
the default store landing page:

```bash
bundle exec rails s
```

At this step, we have a full-fledged online store. One might want to tweak some
styles before sending it to production, but for our testing purposes, it's just
what we need. We are now ready to setup Cypress.

### Cypress setup

Similarly to how [react-rails](https://github.com/reactjs/react-rails) gem is used
to integrate React components with Rails views, we will use [cypress-on-rails](https://github.com/shakacode/cypress-on-rails)
gem to integrate Cypress with Rails tests. The new gem is a light wrapper around
Cypress that augments its functionality allowing us to prepare application state
using factories or custom Ruby code. Following the gem's getting started [guide](https://github.com/shakacode/cypress-on-rails#getting-started),
add the cypress-on-rails gem to the Gemfile and run the generator:

```ruby
# Gemfile

group :test, :development do
  gem 'cypress-on-rails', '~> 1.0'
end
```
```bash
bin/rails g cypress_on_rails:install
```

This will both add the cypress npm package and setup the Ruby integration. To ensure
that Cypress is ready to run tests against our application, run the application
server in a test environment on port 5002 and in a separate window run Cypress:

```bash
# start rails
bundle exec rails server -e test -p 5002

# in separate window start cypress
yarn cypress open --project ./spec
```

You might also need to precompile assets before running Cypress. The command `cypress open`
will launch a test runner window with some sample tests scaffolded for us by Cypress.
We will move on to substitute the sample tests with our own. Now, notice how simple
it is to add Cypress to a Rails project, a single gem and no external dependencies
like servers or drivers required.

However, let's throw in a few more gems to help us with arranging the application
state. We want to empty the database before each spec and then create the data
required by each test scenario.

As usually, we delegate the database cleaning job to the [database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) gem.
Add the gem to the project and then key in the bellow scripts:

```ruby
# spec/cypress/cypress_helper.rb

require 'database_cleaner'
```
```ruby
# spec/cypress/app_commands/clean.rb

DatabaseCleaner.strategy = :truncation
DatabaseCleaner.clean
```
```js
# spec/cypress/support/index.js

import './commands'
import './on-rails'

beforeEach(() => {
  cy.app('clean');
});
```

The above scripts configure the gem and then run it (`cy.app('clean')`) before
each integration test. Now lets prepare the test data with FactoryBot. Add the
`factory_bot_rails` gem to the project together with the following code:

```ruby
# spec/cypress/cypress_helper.rb

require 'database_cleaner'
require "factory_bot"
require "spree/testing_support/factories"
require "carmen"

Dir[Rails.root.join("spec", "support", "factories", "**", "*.rb")].each { |f| require f }

FactoryBot.find_definitions
```

We now have access to both the FactoryBot library and all the factories provided
by Solidus (e.g. users, orders and products).

### Add Cypress tests

Some online stores require their customers to sign in prior to the checkout. Solidus
comes with user session management functionality built-in and for us it's a great
test subject to begin with.

Our first test will verify that only registered (persisted) users can sign in. Users
that cannot be found in our database will be presented with the corresponding sign
in failure message.

Following the Arrange-Act-Assert (AAA) testing pattern, we first arrange the application
state for our planned scenario. We will execute our tests against an application
with one existing user. We will use a user factory imported from Solidus. Key in
the following:

```ruby
# spec/cypress/app_commands/scenarios/sign_in.rb
FactoryBot.create(:user, email: 'user@example.com', password: 'test123')
```

With the state arranged, we move on to describe user actions and assert the desired
outcome. Note that Cypress leverages other well-known libraries to write and organize
tests. Specifically, Mocha provides TDD-like syntax to structure the tests
(think decribe() - beforeEach() - it()). Likewise, Cypress wraps and extends Chai
for writing assertions (think should). Moreover, with cypress-on-rails gem we are
able to run our factory defined above by calling cy.scenario('sign_in'). Type in
the following:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
	  cy.scenario('sign_in');
  });
});
```

Great, with above we declared that we want our `sign_in` state preparation script
to run before any of the following tests. Now, let's describe a scenario in which
an existing user attempts to login:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    cy.get('#link-to-login').click();
    cy.url().should('include', '/login');
    cy.get('[name="spree_user[email]"]').type('user@example.com');
    cy.get('[name="spree_user[password]"]').type('test123');
    cy.get('input.button')
      .contains('Login')
      .click();
    cy.get('.flash.success')
      .contains('Logged in')
      .should('be.visible');
  });
});
```

The test code is self-explanatory. The user visits the index page and clicks on
the login button, which redirects him to the login page. On the login page, the
user enters his valid credentials and clicks "Login" button. As the credentials
are valid, we expect a login success message to be displayed. Now let's verify
that a user with invalid credentials cannot sign in:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    ...
  });
  it('does not sign in user with invalid credentials', () => {
    cy.get('#link-to-login').click();
    cy.url().should('include', '/login');
    cy.get('[name="spree_user[email]"]').type('wrong_email@example.com');
    cy.get('[name="spree_user[password]"]').type('test123');
    cy.get('input.button')
      .contains('Login')
      .click();
    cy.get('.flash.error')
      .contains('Invalid email or password.')
      .should('be.visible');
  });
});
```

It's not ideal, the duplicate code is screaming at us. We will return to it, but
for now, we focus on executing the tests. Thus, we run the server and the test
runner as we did previously. Running the tests we should see the Cypress test
runner in action:

![](https://cdn.sanity.io/images/kqgmf0g2/production/68cd6c0e45890f82c41b5e8dca129820634d99dc-2104x1252.gif?fit=clip)

Great! Our tests are successfully executed: Cypress test runner opens a new browser
window and mimics the user actions as described in our test scenario.

Notice how the browser window is divided into two parts with the command log on
the left and our application on the right. The command log displays all the executed
commands together with application data such as network requests, page loads, etc.
Notably, with each performed action Cypress takes a new DOM snapshot. This series
of snapshots enables us to navigate the command log and see the state of our application
back in time. Furthermore, remember that we are in the browser. Open the DevTools,
inspect the DOM or click on any command from the log and see it's full description.
One can  also put a `debugger` in the application's code or within a test
scenario (`cy.debug()`) and inspect the state with the browser console. Are you
working with a [Redux](https://redux.js.org/) store? Plug into that too. Overall,
the interactive test runner enables us to better understand our application and
quickly reason about our tests, which makes testing a more enjoyable experience.

Finally, let's refactor our user sign in spec to remove duplicate code. One possible
solution is to use Cypress custom commands, which allow one to group together common
user patterns. We extract the repeating user sign in logic into a custom command:

```js
// spec/cypress/support/commands.js
Cypress.Commands.add('login', (email, password) => {
  cy.get('#link-to-login').click()
  cy.url().should('include', '/login')
  cy.get('[name="spree_user[email]"]')
    .type(email)
  cy.get('[name="spree_user[password]"]')
    .type(password)
  cy.get('input.button')
    .contains('Login')
    .click()
})
```

Cypress will load the new command for us so we can start using it right away:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    cy.login('user@example.com', 'test123');
    cy.get('.flash.success')
      .contains('Logged in')
      .should('be.visible');
  });
  it('does not sign in user with invalid credentials', () => {
    cy.login('wrong_email@example.com', 'test123');
    cy.get('.flash.error')
      .contains('Invalid email or password.')
      .should('be.visible');
  });
});
```
## Add Cypress to CI

Nearly any software product involves an engineering team continuously integrating
small code changes into a shared repository. Without special measures, such frequent
updates by different team members can lead to accumulation of bugs. We want to prevent
that. We will catch the bugs early by running our Cypress integration tests on each
commit to our shared remote repository.

In addition to Cypress we will also run RSpec to demonstrate a real scenario with
various test suites running in parallel. Furthermore, we will also run in parallel
the individual tests within each test suit to decrease the overall build time.
Specifically, we will run Cypress test files in different containers, in parallel.
We will highlight the interesting configuration parts, but please find the full
configuration in the [project repository](https://github.com/nebulab/cypress-store/blob/master/.circleci/config.yml).

First, we declare that our `build_rspec_cypress` workflow consists of two jobs
that we wish to run in parallel:

```yaml
# .circleci/config.yml
workflows:
  version: 2
  build_rspec_cypress:
    jobs:
      - rspec
      - cypress
```

The cypress job will run the required general steps like database preparation and
asset compilation after which it will run the Rails server in the background:

```yaml
# .circleci/config.yml
- run:
	  name: Run rails server in background
	  command: bundle exec rails server -e test -p 5002
	  background: true
```

Yes, just like we did on our local machine. However, we will need to wait for
the server to start before executing integration tests against it:

```yaml
- run:
	  name: Wait for server
	  command: |
	    until $(curl --retry 10 --output /dev/null --silent --head --fail http://127.0.0.1:5002/admin); do
	        printf '.'
	        sleep 5
      done
```

Finally, the server is up and we can run our Cypress tests:

```yaml
- run:
    name: Executes Cypress end-to-end tests
    command: |
      export TEST_FILES="$(circleci tests glob "spec/cypress/**/*.spec.js" | circleci tests split --split-by=timings)"
      export TEST_FILES="$(ruby -rshellwords -e'print ENV["TEST_FILES"].shellsplit.join(",")')"
      echo yarn run cypress run --project ./spec --spec $TEST_FILES
      yarn run cypress run --project ./spec --spec $TEST_FILES
- store_artifacts:
    path: spec/cypress/videos
- store_artifacts:
    path: spec/cypress/screenshots
```

The test files will be split to run in parallel in multiple containers. Change `parallelism: 2`
in the configuration file to the desired number of containers, but make sure it is
lower than the number of test files. Finally, configure CPU and RAM according to
your needs with the `resource_class` entry.

## Summary

In this article, we covered a lot of ground. We started with a discussion of the
new Cypress browser-integrated architecture. From there we initiliazed a new Rails
application to see Cypress in action. We defined our test scenarios with JavaScript
and prepared application state with Ruby. Finally, we setup parallel execution of
Cypress tests as part of our continuous integration process.

The Nebulab