My two most recent employers each had a day of the month dedicated to either learning or tackling tech debt. In both instances, I did not enforce them within my organization as they demonstrate problems in the broader engineering organization. If a company has these, you can smell problems from a mile away.

So why are these dedicated days for learning or tackling tech debt smells and what are better solutions to problems they’re trying to solve?

Smells

Contrast from normal work

Dedicated days imply a disparity from normal work. A day dedicated to tech debt implies you aren’t tackling tech debt otherwise. A day dedicated to learning implies you aren’t learning otherwise. These statements may not necessarily be true, but you generally do not create dedicated days unless this was historically the case.

Inability to collaborate with product managers

Generally, engineers are unable to tackle tech debt, and instead of trying to negotiate the roadmap with product managers, engineers instead negotiate time, e.g. 1 day a month where product managers have no say. The reason could be engineers’ inability to convey the impact of tech debt or the company being a feature factory.

Patronizing other teams

Perhaps a team, e.g. a platform team that works as a dependency of other teams, perceives another team as chaotic. To help them, they help champion a tech debt day since they assume that’s the cause for all the post-mortems.

Lack of engineering excellence

Dedicated learning days generally mean the engineering team is not learning new technologies or architecture. In the past, this was because work was very operational with engineers writing migrations or updating configurations instead of building self-serve tools. Other times, work was pure business logic and there was no architecture involved, specifically in a monolithic Rails application, so there was not much learning to be had.

Ineffectiveness of Dedicated Days

Not only are these dedicated learning or tech debt days smells, but they are also ineffective for many reasons:

• People tend to schedule meetings on these days anyway, making them less useful. The only way to avoid this is to block calendars organizationally which generally does not work.
• One day a month is generally not enough to learn anything meaningful or tackle any meaningful tech debt.
• Learning days are generally self-directed, meaning people learn by themselves, which is not as effective as having a mentor or having a business purpose.

Alternatives to Dedicated Days

Here are some better alternatives to having dedicated days:

Improve Product and Engineering Collaboration

As an engineering lead, it’s imperative to collaborate closely with product managers. You are responsible for teaching them what the product is; a product manager is not just about rolling out features. You need to teach them about technical debt and the architectural short-term and long-term trade-offs for shortcuts. It’s important to align through something like OKR goal-setting.

Match Projects to Engineers

As an engineering manager, it’s important to match projects to engineers. If an engineer does not feel fulfilled by their current work, find work that will fulfill them lest they leave. One-off projects or loaning them to other teams may work.

Allocate Capacity Towards Learning & Tech Debt

Aside from aligning the product and engineering roadmaps, you could tactically tackle tech debt by allotting a percentage of your engineering capacity to platform initiatives. This is usually my go-to strategy as it allows us to actually measure and plan platform initiatives and I have never gotten push back from product managers as long as they understand the initiative. For example, dedicating 10% of frontend engineers and 20% of backend engineers to platform initiatives per quarter may be sufficient for your company. You can extend this from team level project planning to organization-level roadmap planning.

Cross-pollination via Code or Architecture Reviews

Avoid having any engineering team working in silos and encourage code and architecture reviews across teams. Have teams create and share docs and invite the entire organization to comment. Taking into account more perspectives helps avoid clear deficiencies in your code or architecture.

Rotation or Exchange Programs

Instead of spending a day a month learning something, spend two weeks a year embedded in another team that could help you learn the ins-and-outs of their domain. For example, you could have engineers rotate with an SRE or infrastructure team to better improve your platform.

Planning Learning and Innovation

Plan, say, 5–10% of your work with learning and innovation that have some sort of business impact. Having business impact will convince stakeholders to prioritize it and many stakeholders believe in dedicating time towards innovation. These projects could be stretch, research projects with a very low chance of success. Examples are 3D printing, automating something with Alexa/Siri/etc. or with IFFFT.

Learn and Tackle Tech Debt Every Day

Serving the business and building a healthy engineering organization is not dichotomous. Mastery through learning every day and especially learning how to not add tech debt to a system is key intrinsic motivator for keeping and growing engineers.

When scanning through applicants’ resumes, it’s pretty easy to spot H-1B candidates just by reading the top third of the resume’s first page. This could pose a problem for many of these candidates as hiring managers and recruiters may find these resumes difficult to understand. Here are some tips on making your resume look more like U.S.-based candidates’ as well as have a better resume overall, even if you aren’t an H-1B candidate.

Reverse Chronological Order

The first thing a hiring manager wants to see on your resume is your current or latest position. Don’t make this difficult to find—it should be on the top third of your resume. Continue to list your experience in reverse chronological order with the most recent experience first since the more recent experience is more relevant. The only exception to this is to have a separate “Education” section below your professional experience which would otherwise be interlaced with your professional experience.

Education Doesn’t Matter

Unless you are a new graduate, your education does not matter. Your last professional experience is a much better signal than the university you attended. For the most part, all software engineering bachelor’s and master’s degrees from accredited universities in the U.S. are treated equivalently.

Internships > Education

Again, education does not matter, especially if you have internship experience, which counts as professional experience. An internship at a well-known company is a better signal than the university you attended. The best signal is if you have two back-to-back summer internships at the same company — clearly you are great employee!

1–2 Pages

In the U.S. tech industries, we want a resume, not a curriculum vitae. CVs tend to be long and descriptive; they are more suited for other industries like academia, not the tech industry. A resume should be at most two pages with a reasonably sized font (between 10–12px).

A Summary is a Few Sentences, Max

Keep your summary, blurb, or cover letter short. Only provide necessary details such as dealbreakers (e.g. remote work only) and what you want to work on (e.g. React and GraphQL). List character references you may have at the company as well as people you’ve met through recruiting.

Conciseness is a Skill

A short resume demonstrates a very valuable skill in engineering: conciseness. Are you able to describe a problem in a few words? Are you able to solve a problem with minimal code? Do you value the audience’s time by making your communication brief? It may be difficult to write a concise resume, but avoid a long one—a long resume demonstrates a lack of both conciseness and empathy for the reader.

Minimal Personal Details

Don’t add information about your marital status, family, personal hobbies, or passions unless they are relevant to your career. For one, it elongates your resume by adding irrelevant information. However, the biggest reason is that, in the U.S., employers’ asking about certain personal information opens up the employer to discrimination lawsuits, so it’s best for both parties to avoid this by not adding personal details to your resume at all.

No Headshots

Don’t put your headshots in your resume as your looks is not an indicator of your performance as a software engineer. Many cultures tend to put headshots in their resume, but they usually aren’t as diverse and sensitive to diversity as the U.S. Adding your headshot to your resume may make hiring managers discriminate for or against your looks, both of which could be a liability for the company.

Details to Exclude

Personal information should remain personal; only put enough personal information for potential employers to know that you are hire-able. Some don’ts are:

• Your religion, sex, gender, sexual orientation, and date of birth are generally not relevant
• Just put your current city; employers don’t need your full address until you’re being hired
• If you think your name may be open to discrimination by hiring managers, abbreviate your first or last name and make sure your LinkedIn profile matches!

Formatting

PDFs, not Microsoft Word

Many software engineers and engineering hiring managers do not have Microsoft Word as many use Google Apps instead. Word documents will be incorrectly reformatted by Google Apps or Apple Pages, messing them up entirely. Send your resume as a PDF, which is a standardized file format, so that the recipient can read your resume as intended.

Avoid Large Skill Word-Clouds

These tend to be useless, especially if they are large. Think about what you want to convey to the hiring manager and recruiter and just summarize those such as, “Full-stack React and Express.js Engineer”. As a hiring manager, I primarily care about what you’ve worked on and what you want to work on and I look into your recent experience for this, not the word cloud.

Additionally, many candidates tend to list skills that they haven’t used in years in the word cloud and thus are no longer relevant. It’s better to embed your skills into your experience so that your skills are described within context—when you used and developed these skills and what role and position you were in.

List Your Work Authorization

At the bottom of your resume, list your work authorization status such as “requires H-1B sponsorship”. Even I list “U.S. Citizen” at the bottom of my resume because recruiters often ask whether I need visa sponsorship. This will help weed out companies who would not sponsor your visa at all. Of course, this depends on the type of companies you apply to. Many companies either do (e.g. large tech companies) or don’t (e.g. defense companies) sponsor visas, but some companies (e.g. early stage start-ups) may sponsor your visa if you stand out or if they have sufficient VC backing.

Summary

Hopefully this helps you understand the U.S. tech industry better, which strives to be a progressive meritocracy, but sometimes falls short. Have any questions? Feel free to ask me questions on LinkedIn.

I’ve heard many complaints about Storybook StoryShots and Jest snapshot testing at work, online, and various Slack groups. Some of the complaints I’ve heard are:

• It’s annoying because you always have to update the snapshots
• It makes the git diff very large
• It doesn’t actually guarantee anything
• It creates a false sense of security

Some of the points above are just irrelevant—you should never have to worry about large git text diffs as this is what git is optimized for. Others simply miss the organizational, technical, and other benefits of having StoryShots and snapshot testing, which is more important to me as an engineering manager. By always updating snapshots locally, you’ll reap many benefits with the minimal cost of running tests.

StoryShots and snapshot testing do not assert correctness

A snapshot simply stores some states in a moment in time or git history. A changed snapshot means that something has changed, but does not necessarily mean that the functionality is now broken or incorrect like a failing test otherwise would. Thus, I wouldn’t even call it a “test” — it’s more like a validation step. A snapshot “test” failed because the output change and an engineer needs to manually validate it.

StoryShots and snapshot testing is more like static checking

Write tests. Not too many. Mostly integration.

Many people see snapshot testing as a less useful form of unit testing, but a better way too see snapshot testing is as a more useful form of static checking and linting. Linting tools check that your code is valid without executing it whereas snapshot testing checks that your code is valid by executing it; both do not check for correctness. The fact that snapshot testing actually runs your code allows you to find bugs that linting would not be able to find. There are plenty of typos, bad imports, or bad dependencies that I’ve caught with no effort with StoryShots.

StoryShots encourages you to build view components

If you’ve built a complex component with data fetching and rendering, you’ve probably struggled with StoryShots as your component is dynamic and nondeterministic. For example, if your component depends on the current date, your snapshots will start failing the day after you merge your code. StoryShots and snapshot testing encourages making deterministic view components and to pass nondeterministic parameters as props. It encourages building separate data loading components or containers whose functionality can be unit tested separately.

StoryShots is a step towards visual regression testing

Visual Testing with Storybook

With only deterministic view components as stories, your team will be able to rely on visual testing to find visual regressions. With visual regression testing, your HTML DOM structure snapshots will matter much less—just manually validate the visual changes. The organizational benefit with visual regression testing is that you can visually show the changes to non-technical stakeholders like designers and product managers and catch issues sooner.

Snapshot testing encourages engineers to run tests locally

A failed snapshot test means the engineer did not run the test locally (i.e. did not intervene manually), which they should be doing whenever possible. The fact that PRs are failing because snapshots weren’t updated means that the engineer probably didn’t run the tests locally.

Snapshot testing helps you understand the dependency tree

Sometimes you will, in fact, run tests just for your component locally, but in CI, where the entire test suite is ran, you’ll find that your change also affected another component’s snapshots. These snapshot tests are a way to understand the dependency tree and know who are impacted by your changes or whose changes impact you.

Snapshot history is a paper trail for debugging issues

Snapshot histories provide a way for you to debug and issues in your code base. Snapshots allow you to know which PRs changes the structure of certain components, allowing you to more quickly find a culprit for an issue via git during an outage.

StoryShots allows engineers to skip writing their own snapshots

I hear people complaining about StoryShots, but then write their own snapshot tests for their component. This is just adding work on their plate and additional maintenance for the team. When you write a story and add StoryShot testing, you have snapshot testing for free. Of course, StoryShots only handles snapshots for views — non-view snapshots will still need to be done manually (such as tests for a component’s state machine).

How to make snapshot testing better

To avoid complaints in your organization while achieving the marginal benefits of StoryShots, I recommend these changes:

• Use shallow rendering to avoid large snapshots that are prone to breakage
• Run StoryShots tests separate from your other tests
• Always run StoryShots with -u locally
• Create a CI job that automatically updates snapshots when necessary
• If any stories or storyshots get annoying, fix it or delete it

When starting with React, many people being using redux with redux-thunk. After first seeing it many years ago, I quickly smelled many anti-patterns and tried to move teams off of it. Nowadays, with Apollo GraphQL, React Context, and React Hooks among other features, there’s less reason to use it anyways.

GitHub - reduxjs/redux-thunk: Thunk middleware for Redux

The anti-patterns became much more apparent when working on larger teams. It doesn’t matter which frameworks you use on your personal TODO app, but when it comes to organizations, frameworks matters a lot. As a corollary to Conway’s Law, poorly architected code can lead to poorly architected organizations and vice versa; frameworks help decide your architecture. I’ve seen the effects of poorly architected code first-hand with redux-thunk.

Middleware is a smell

Not all middleware is bad, especially if it’s logic that must be executed with every function call. However, it is a layer of abstraction that makes your code more difficult to understand. As a maintainer of Koa and previously Express, I felt the pain of middleware — engineers requested various middleware that handle everything for them. For example, engineers may think they want middleware to access req.currentUser on every request. However, instead of middleware, what engineers really want is a method like const currentUser = await req.getCurrentUser() which retrieves the current user only when requested. Unfortunately, for most pre-async function, callback-based frameworks like Express, this would’ve been a pain.

In fact, this has been my perspective on the complexity of the JavaScript ecosystem: so many frameworks, so many opinions, and so many libraries were created because people found JavaScript’s asynchrony complex and tedious. People’s pain with callbacks motivated them to create frameworks to halve the number of lines of codes they had to write. Most of these solutions involved “middleware”, but with the advent of async functions, there is less need for middleware.

Middleware should be using sparingly and generally for two reasons: logging and debugging. Middleware should generally not be used for business logic; any middleware that adds business logic to your system will make your system inflexible and obtuse. Although redux-thunk middleware does not contain business logic, it pushes business logic execution to the middleware, hidden from engineers who don’t know what they’re looking for. As an organization matures, this has many effects such as a decreasing velocity, a decreasing inability to innovate, and an increasing propensity to solve problems through poorly architected microservices just to escape their current trap of poorly architected middleware.

getState() obscures data’s and action’s dependencies

As mentioned in the Idiomatic Redux Series, getState() breaks one-way data flow. A more practical perspective of this anti-pattern is that it obscures what the data flow is—it obscures how data and actions are dependent on each other by creating implicit dependencies on the current state. Writing logic with getState() will be very easy at the beginning, but once you try to untangle and understand your thunks, especially when migrating to a new framework, you’ll realize that you just created a ball of mud.

This dependency spaghetti will make migration and innovation more difficult. You may try to migrate a page to use Apollo GraphQL using React Hooks, but you won’t realize that another page relies on data generated from your thunks until someone reports that broken page. This is especially true when your organization also has messy team dependencies where all the teams are working on the same repository without any clear delineation of ownership, which I’ve never found to be not the case. Organizational dependencies are difficult problems to solve, but code dependency problems are entirely under engineering’s control.

thunks can cause infinite recursions

Perhaps the most painful experience with redux-thunk is when it causes an infinite recursion. Because data and action dependencies are not explicit, a developer error could cause an infinite recursion (e.g. a thunk inadvertently calls itself later), causing pages to hang. This is especially true when you scale your organization and have multiple teams working on the same codebase—one team may inadvertently cause an infinite recursion because they didn’t know how their code affected other teams’ code. As a corollary to Conway’s Law, this specifically happens when there’s coupling: two teams and their code depend on each other.

I’ve actually dealt with this in production multiple times. The worst aspect of this error is that it’s purely client-side, so a simple deployment won’t fix it—you’ll have to tell your users to force exit their browser and clear their cache. It’s also pretty difficult to debug—you’re digging through multiple thunks that interact with each other without any explicit dependencies. It’s like trying to understand the Dark timeline (spoilers) while a gun is pointed at your head.

Figuring out how to split teams without coupling them or their services is a difficult problem to solve as splitting teams involves much more than just technical considerations. However, you shouldn’t make this a more difficult problem by relying on frameworks that make code coupling easier.

Don’t use redux-thunk

There isn’t a good reason to use redux-thunk. It’s fine for small projects, but if you have to scale technically or organizationally, you’ll run into architectural problems. It’s best to avoid it from the beginning by not depending on it at all.

When I first became a manager, my boss told me, “We just interviewed this person and they were great. We’re going to hire them under you”. I was pretty excited at first, but after I looked at their resume, I realized that they didn’t actually have any professional engineering experience. The lack of experience wasn’t the problem—the problem was that they were paid more than they should, especially compared to their peers. Thus, I’ve written down some heuristics on how to spot bootcamp grad resumes so that hiring managers and recruiters can hire them at the correct level.

Is their last experience an open source “project”?

If you click on the candidate’s “experience”, does it link to a project or a site that is open source, but is built to look like a company? Do you see a GitHub icon at the top or bottom of the page? Very few companies’ core products are open source , and the ones that are, you’ve probably heard of. The fact that the candidate’s latest experience is open source is a smell that this experience is not professional. Look deeper and look at whether the project is hiring, the about us, whether it has a Wikipedia, Crunchbase, or similar article written about it to see whether this experience was professional.

Contributing to open source projects is a great way to build skills and resumes, but as a hiring manager, you want to be able to discern whether a candidate’s experience is professional. Many bootcamp projects are resume builders designed to look like companies. Be wary of projects listed in the experience section as they may not always be professional experience.

Note that this heuristic doesn’t apply to projects outside of “experience”. Projects listed elsewhere such as a “projects” section generally convey non-professional, passion projects.

Is their last experience a devtool?

Recently, bootcamp candidates’ team projects tend to be devtools—is the above company an open-source devtool? As my bootcamp graduate friend told me, instead of building a useless beer or wine app, the bootcamp grads would at least have dove deep into a technology such as React, Storybook, or HTTP request testing when working on a devtool. I personally don’t buy this argument since you don’t need deep understanding of the technologies you are using to be a great product engineer.

Does their last experience list contributors?

Another heuristic that the experience is a bootcamp project is that you’ll usually see a list of contributors on the project site. I personally don’t see the point of this—since this project is usually open source, you can go to the GitHub project and see the list of contributors through GitHub’s UI. Even for my open source projects and contributions, I don’t care much about the list of contributors as the list becomes insanely long and many people are anonymous. For professional companies, you almost never see a list of contributors.

Is there last experience at a bootcamp?

Many bootcamps have fellowship programs where if a candidate can’t find a job or doesn’t want to find a job, they’ll work for a bootcamp, usually the one they graduated from. Here, there will be significant title inflation—engineers will often have “Senior” or “Fellow” titles, which do not map at all to industry standards. A bootcamp’s “Senior” is going to be an industry standard “Junior”—three months is simply not enough time to reach Senior.

Do they have a “Projects” section?

As mentioned above, most bootcamps have team projects, which grads then add to their resume. Both bootcamp graduates and junior engineers tend to have a “Projects” section, but many bootcamp graduates tend to not show their bootcamp experience as many feel there is bias against them. Take a look at these projects and see whether it’s a solo or group project.

Showing the projects is totally fine if you have no other experience, but it doesn’t make sense if you have professional experience. Side projects are generally frowned upon at companies (e.g. they want you working at their company only) and may cause legal problems (e.g. potential conflict of interest). If you have professional experience, I don’t recommend adding any side projects unless it’s revenue-generating, VC funded, or has decent traction (e.g. has a bunch of GitHub stars).

If you’re a bootcamp graduate or junior engineer, I don’t recommend adding projects to your resume unless you add tests and the project is actually live. I’ve never seen a bootcamp grad whose projects have tests, which would immediately move them to the top of my list. I also want to see what you’ve created, but I am not going to pull your repository locally, so please host your creation. GitHub Pages is free!

Training a Discerning Eye

Hopefully these heuristics help you spot a bootcamp graduate and allow you to hire them at the appropriate level. This doesn’t mean that their worse candidates or that they should be avoided—I’ve hired and worked with many bootcamp graduates that were great software engineers. Instead, the only problem I’ve experienced is when bootcamp graduates aren’t properly placed in a hiring pipeline.

NOTE: This article has had many revisions as many phrases sounded anti-bootcamp graduate. Please contact me on Twitter if you have any constructive criticisms as this is not the case!

node_modules/.cache is a community-standard cache folder for storing files. Many projects such as ava, nyc, storybook, and many webpack loaders and plugins use this folder by default. With some configuration, you can speed up your CI and developer experience by pointing other caches to this folder and persisting it across builds.

GitHub Actions Setup

github-actions-workflow-templates/node.js.yml at master · jonathanong/github-actions-workflow-templates

Here’s an example GitHub Action that caches node_modules/.cache, creating a new cache value after every run with the suffix -run-id-${{ github.run_id }}. This is in contrast to the node_modules cache that relies strictly on the hash of the manifest files. In other words, the node_modules cache should only change when the manifest changes, but the node_modules/.cache cache should be constantly updated.

Use node_modules/.cache for your commands

Here are some commonly used modules and how to set up their cache directories:

• jest: set cacheDirectory: 'node_modules/.cache/jest' in your config
• stylelint: run with --cache --cache-location=node_modules/.cache/stylelint
• eslint: run with --cache --cache-location=node_modules/.cache/eslint
• babel-loader: set cacheDirectory: 'node_modules/.cache/babel-loader in your config

With these cache directories set up, I have experienced subsequent test and lint runs take a fraction of the time, both locally and on CI. I’ve been able to eliminate a lot of workarounds with this performance gain such as hooks that only lints changed files.

Consider caching node_modules/.cache instead of node_modules

When set up properly, you may only need to set up caching on the .cache folder, especially if your npm ci runs very fast.

Some reasons you may not want to cache your entire node_modules folder are:

• On a self-hosted runner, you can rely on npm's caching mechanism, which already caches package tarballs on the runner (actions do not run in isolation, so they will have access to this folder)
• Self-hosted runners will probably have a weaker connection to the cache store, making the cache slower
• node_modules tends to become large and each GitHub repository has a cache limit (currently 5GB), so caching your node_modules may evict your other caches sooner

Here are some cases you may still want to cache your node_modules:

• Your node_modules folder is very large and caching is significantly faster than running npm ci
• You have a lot of postinstall build scripts, e.g. binaries that need to be compiled

My recommendation is to start with just caching node_modules/.cache, then check whether caching node_modules as well will speed up your CI.

Every company I’ve worked at/with has struggled to prioritize engineering work against product work. Most of them have tried to solve this by dedicating a percentage of their engineering capacity on engineering work. If done right, allocating capacity across categories provides a feedback loop that can provide insight into your team’s work and will help steer your team towards healthy collaboration with product. The goal is to align on product-engineering roadmap, which may or may not end up using a framework like this.

Categories

First, let’s define a few categories of work.

Innovation

Work categorized as innovation are high-risk, high-reward and have a low chance of success. Innovation is necessary to avoid the local maxima problem, otherwise you may just be adding diminishing marginal gains to your product. This category is a privilege; the ability to innovate demonstrates the level of your product’s maturity.

Feature

A feature is generally any work requested by a product manager or stakeholder.

Platform

Platform work is either:

• Creating capabilities to enable Features and create Innovation
• Reducing Operational overhead

Platform work is an investment into the product to make it more flexible, adaptable, maintainable, scalable, etc. Although it is engineering-driven, it provides opaque benefits to the end user and to the business. It is the responsibility of engineering to clarify these benefits to stakeholders.

Operations

Operations work is necessary toil to keep the business running. Generally, operations work should either not exist or be automated. Examples include:

• Bugs
• Engineering Operations such as manual migrations
• DevOps such as manual deployments and manual QA
• Outages and Incident Management
• Business Operations such as business logic changes

These operational tasks are mutually exclusive from the other categories. Some of these operational items are intentional (e.g. MVP-launch of a product that has not been automated yet). Others may be caused by a lack of user stories (e.g. from features) or from incorrectly implemented services. Operations is not owned by either product or engineering—it is a common enemy of both.

Innovation/Features/Platform Categories are not Mutually Exclusive

Don’t struggle to categorize work—categorization is just a framework to discuss how to plan work. Deliberating on the correct category for a work item is not going to improve the output of the work item. Create some simple heuristics to quickly categorize work. For example, if it’s product-driven, define it as a feature; if it’s engineering-driven, define it as platform work. Feel free to create new categories and break categories up.

Define an Ideal Allocation

Work with your product managers to define the ideal allocation of work depending on the maturity of your product. Here’s an example of an ideal allocation:

• Innovation: 10%
• Feature: 60%
• Platform: 30%
• Ops: 0%

You will never reach the ideal allocation, but it’s important to align on the goals such as: create a healthy product, increase velocity, and minimize operational overhead.

Create a Feedback Loop

Once you’ve align on the goals, it’s time to create a feedback loop.

Measure

After every planning period (e.g. quarterly), measure the work allocation. In JIRA, you can export your team’s completed tasks for the last few sprints to a Google spreadsheet, then categorize and visualize within the spreadsheet.

Reflect

Reflect on the work allocation in your last planning period. Here are some questions you may ask your team:

• What was surprising about the work this period?
• What can product and engineering agree on for the next planning period?
• What do we need to automate to improve velocity?
• How does this work allocation affect morale? Was there too much toil?

Adjust

After reflecting, agree on some action items for your teams. Some action items could be:

• Have product and engineering collaborate for causes of the bugs
• Prioritize and limit the intake of operational requests from stakeholders
• Add some platform initiatives to reduce engineering operations
• Advocate for increased engineering capacity

Plan

When planning for the next period, only cap how much of each category you’ll dedicate. For example, if your team completes 100 story points every period, only plan up to 60 story points for features, 30 for platform, and leave the remaining 10 for potential operational tasks.

Repeat

As you repeat this cycle, you’ll hopefully reach product-engineering alignment.

The Process is for the Goal

Remember that this process only exists to reach the goal of product-engineering alignment. If you already have alignment, then you probably don’t need this framework at all (although the graphs would be a nice visualization regardless). For example, one of my teams is working on a PHP to React microfrontend migration, which we don’t even categorize as platform or feature—instead, we try to minimize unrelated feature and operational work.

Recently, a bunch of Dependabot PRs that required GitHub Action Secrets began to fail, which brought me to this article from GitHub:

GitHub Actions: Workflows triggered by Dependabot PRs will run with read-only permissions | GitHub Changelog

Which lead to this article about preventing pwn requests:

Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests

By no longer having access to repository secrets, Dependabot PRs in my organizations began to fail because they relied on a personal access token secret for fetching private GitHub Packages, which is currently the only authentication method for accessing private GitHub Packages outside of the current repository. I read these articles multiple times and still didn’t understand how to fix Dependabot PRs. Scouring the internet, I found a significant amount of frustration and a lot of complicated work arounds.

After a few days, I realized that there was a simple solution for my organizations.

Disable Forking of Private Repositories

In the Preventing pwn requests article, the main attack vector GitHub is trying to defend against is malicious authors, but if your organization only has private repositories that do not allow forks, all your authors should be trusted (otherwise they shouldn’t be in your organization).

With proper branch protection in each repository, there isn’t a good reason to allow members of your organization to fork private repositories. Forking makes perfect sense in public, open-source projects, but not for private repositories. Thus, don’t allow forking of private repositories:

Only Enable Secrets for Private Repositories

Next, don’t share secrets in any of your public repositories. Your public repositories should not need any and, if they do, you can set different secrets for them. Note that “private repositories” is the default option, so you are probably already doing this.

Send Secrets to Workflows from Fork Pull Requests

Since Dependabot PRs are treated as fork PRs, just allow sending secrets to fork PRs, but don’t allow forks in your organization. This will enable secrets just for Dependabot (that I am aware of).

It’s like GitHub never made a change!

Things to keep in mind

These settings just circumvent the protections GitHub is trying to provide you. To minimize the vulnerabilities, you should:

• Use lockfiles so that GitHub Dependabot can keep track of any vulnerabilities in your entire dependency tree
• Only use trusted dependencies and consider gating which third party dependencies you allow in your applications
• Try to only use personal access token secrets with read-only access (e.g. reading GitHub Packages) whenever possible—avoid creating PATs with write access

May 26th, 2020 Update: I upgraded to 8TB WD Red HDs and the performance increased drastically since these higher-capacity drives do not use SMR.

Do not use AFP (Apple Filing Protocol)

In the beginning, I used AFP because it’s written by Apple and I only use Apple devices, but of course, this is one of Apple’s proprietary formats that is being deprecated. Instead, use SMB. Synology lists the file-sharing protocols that are supported by each OS.

Is AFP slated to be removed from future versions of macOS?

Set advanced SMB settings

Solved: Slow Transfer Speeds on Synology NAS - Bob McKay's Blog

Bob’s post describes advanced SMB settings for better performance.

• Use at least SMB2
• Disable transport encryption
• Enable opportunistic locking

Disable Media & File Indexing

Media indexing indexes your files for Video/Audio/Photo Station while file indexing indexes your files for Universal Search. Both index your files whenever they change (e.g. create a file, delete a file, etc.) and could slow down your server for a minute or so. These indexing services quickly become a bottleneck.

A few downsides of removing indexing are:

• Media indexing: no more thumbnails for your media
• File indexing: universal search is slower

Both of these downsides were acceptable to me since I do not use Video/Audio/Photo Station.

To disable Media indexing, go to Control Panel > Indexing Service and remove indexed folders. You probably also want to disable “Enable video conversion for mobile devices” as well.

To disable File indexing, go to Universal Search, click settings (the gear icon), and remove indexed folders.

Your router probably doesn’t support Dynamic Link Aggregation

While figuring out why my NAS was so slow, I enabled Dynamic Link Aggregation. Then my NAS got even slower. After reading Synology forums, I learned that most routers don’t support Dynamic Link Aggregation (even Synology’s own router!) and enabling without proper support makes your NAS slower. Transferring data between my NAS and my computers would thrash the whole network, slowing everything down. Don’t enable this feature unless your NAS is connected to a router or a switch that supports it.

Cannot find resource errors

After maybe a day, I’m unable to connect to my NAS even though the drive is still mounted. An error pops up saying, “the original item cannot be found”. The fix is to restart your Finder, but someone in the Synology forums created a script to remount your NAS drive automatically.

Synology Community

Avoid huge share folders

I had a single share folder of about 8TB, which Plex could not even index. So I decided to split the folder into two shared folders and Plex starting indexing both folders and both folders became faster to search through via Finder. Who would’ve thought this would’ve solved anything!

Finally usable

After applying the above fixes, my NAS was finally bearable. Browsing my content via Finder didn’t include multiple seconds of lag. Videos played almost instantly. I finally felt like I got the NAS I paid for.

There are numerous blog posts on how to optimize images, but none are quite straightforward as I would like. The idea behind this post is to give you quick, direct steps to optimize your images using Imgix, though using other services would be very similar.

Only serve your highest quality image as the master asset

Your graphic design team shouldn’t be cropping assets themselves anymore — instead, have them upload master assets to your CMS. Have your web and mobile clients crop images themselves. For Imgix, this also lowers your costs as pricing is based on the active master images per month.

Only upload JPEGs, PNGs, and SVGs master image assets

For compatibility reasons, assets should only be the above types. Do not use WebP images as your source files as they aren’t compatible with many browsers. The general rule to follow is: if your image has transparency, upload a PNG, otherwise, upload a high-quality JPEG. Remember, PNG is a lossless format whereas JPEGs are not.

Don’t serve your SVGs through Imgix

I’ve run into issues where SVGs were served with incorrect headers even though no image transcoding was performed. SVG support in Imgix can be enabled by contacting support, which I never bothered to do.

Setup auto=compress and fit=max as defaults

auto=compress ensures that your images are always compressed. fit=max ensures that your images are only ever scaled-down when used in conjunction with w= or h=.

Set auto=format in every image URL

Unfortunately, auto=format cannot be set as a default value, so you’ll need to add this query parameter to every single image you set in your code. This is a little tedious–I recommend test automation to ensure that all images on our site have this parameter set. This is a large bulk of image optimization as it serves WebP on supported browsers.

Set w= or h= to resize images

w= and h= parameters set the size of an image. Set at least one of these for each image to make sure you’re using an appropriately sized image, especially if your master images are very large. In conjunction with fit=max, images will either be the same size or downsized.

Further Reading

You can read more at Imgix’s API Reference. The only other feature I’ve planned to experiment is fm=pjpg, which should improve perceived load times, but it requires some development work with your CMS as it can only be implemented by images without transparency.