Natik's Journal

This Thing Finally Looks Nice, Clean, and Calm

nate@respawn.io — Fri, 17 Apr 2026 00:00:00 GMT

I remember a year ago LLMs really sucked at putting together beautiful and cohesive web pages. They could get the job done, but it all was very obviously mediocre react. Garbage in, garbage out.

Figured I'd test how it works now, if I use Claude Code's /frontend-design and playwright, and holy hell.

It now reads more like a journal and less like a template — set in IBM Plex Serif with IBM Plex Mono for labels, a cream paper background borrowed from Flexoki, and an Everforest dark mode. The nav went text-only, and the styles are consistent across the site.

Screens below.

Homepage

%% The list of posts stayed the list of posts. Everything around it quieted down — text-only nav, a topic row above the years, a softer background. %%

Post

%% Serif body type takes over. Code blocks sit on a soft surface tint instead of the default blue; the footer rule fades into three command glyphs. %%

Topic

%% Tags became topics: a mono TOPIC eyebrow, a serif subject, a one-line description. The pound sign retired. %%

Colors come from Flexoki (light) and Everforest (dark). Type is IBM Plex. Everything else is just Tailwind tokens in a trench coat.

Slopware of The Month

nate@respawn.io — Wed, 15 Apr 2026 00:00:00 GMT

Over just March and April, I've made a whole bunch of small CLI tools. Some for work, some personal. It's insanely easy to make things like this now, and it's insanely difficult to scope them just right to not burn days and days on stuff you don't need.

I'm not bragging, I'm confessing. It's all slopware, use at your own risk.

brew tap natikgadzhi/taps
brew install {whatever}

slack-cli: read-only Slack CLI for fetching messages, threads, channel history, and search results from the terminal. Used pretty actively in a bunch of my Claude Code skills.
gitbatch: batch-updates multiple git repositories in parallel, with scheduled syncs and auto-stash support for dirty worktrees.
notoma: one-way sync from Notion to Obsidian, with incremental updates, attachment downloads, and database export support. I have a family Notion workspace that is on a year-long trial, and I sync things down from there.
fm: FastMail CLI for reading and searching email. Another personal one - used in Claude Code skill to help me clean my inbox and not forget important emails.

How I Got Hired

nate@respawn.io — Thu, 09 Apr 2026 00:00:00 GMT

How I got hired

Evil Martians, 2010

This was back in 2010 or early 2011, I think. I've met the founding team on a Ruby on Rails meetup where I presented a half-assed pivotal tracker automation service that my friend and I hacked together over a weekend. It marked tickets in-progress / closed based on Github pull request titles, [Closes PROJ-{XYZ}] kind of thing. Alexander had to be a smart ass and ask “Cool, we use Pivotal Tracker, does your thing do HTTPS?”. Anyway, I applied for their software engineer positions, and got a polite no thank you. In a few months, they've been looking for someone who knows Russian, English, and Ruby to translate between and help with sales and engineering, so they reached out.

They ultimately hired me into the role that requireds communications, execution, and half-decent engineering. By the time we had our interviews, I was in a mix of product / engineering roles at a Russian AWS clone, presented at conferences, and ran whole co-sponsorship program with the largest high load / distributed systems conference in Russia. Credentialed.

I only got hired because they've already seen me do the job.

Retail Zipline, 2021

I've worked at Evil Martians for a long time. I loved what I learned to do there! That team hit above it's weight. By 2021, I've worked with several companies I was curious about, and at some point, two of them poked around the “Hey, do you want to join us full time?” topic. Zipline was one of them, Teleport was the other.

Zipline hired me to do what I already did for them for a year. Twice-a-week standups, supporting engineers on both Martian and Zipline side, driving product conversations, and owning problems end to end.

Teleport conversations happened for the same reason – by the time we talked, I've worked closely with their engineering and product managers, and contributed to their plugin ecosystem. Once again, I got into conversations and ultimately got hired to do what I've already proven to do well.

To this day, my team at Zipline is dear to my heart. I've made friends there, true friends I'm still in touch with.

Airbyte, 2023

Then comes the most interesting part. After two years as a ~~director~~ senior eng manager with an overinflated title and understimulated brain at Zipline, I was out for new adventures, and I wanted to break into devtools. But if we follow the principle of “you get hired to do what you already demonstrated doing well”, who would hire me into dev tools if all I have to show for it is a few PRs in Go for Teleport? So I got to work.

Apple

Ah, let's start with some prior history. I've had three years of interviews at Apple, that became a November tradition. First time, it was a referral into XCode Cloud team, with a potential relo to Vancouver, and I didn't make a good impression on the manager, whoops.

Second pass was for a different team, with heavy open source presence, and I really, really wanted to get in. I love this team to this day, but, it didn't pan out, after a long, and a really weird process. That was still 2022 I think, I was at Zipline. Rejection dysphoria is very real in this one ** points into own's head ** so I got to work.

I have a whole Kanban board in Obsidian with mapping Apple's open source projects, my contributions to them, issues I worked on, people I interacted with, and their teams at Apple. I've had a LOT of fun, and I've learned a lot, and I love Swift to this day, despite it's perfectly fucked complexity level in concurrency model.

That work scored me the third pass of interviews, and several follow-ups, and another loop, and some very fun follow-ups. Fool me thrice, can't fool me again.

Sentry

At the same time as the third pass at Apple, I've met some absolutely awesome folks at Sentry and started interviewing with them, and got an offer! My heart have never raced so much as on the call with Zach the recruiter when he brought me the news. Me! In Sentry! In a devtool company! And even remote! YES! And my future boss would also be an amazing human being.

I screwed it up ;) I said I needed some more time (to hear back from Apple), they said okay. I ultimately declined the offer because I was waiting on Apple, and had high confidence. Imagine my surprise when that footgunned me.

Sentry folks were kind enough to go back into a conversation, but for an IC role. So I started, you know, doing the only thing I know how to do — shipping. Oh yeah Sentry is source available under FSL btw, you can go fix bugs that annoy you. I fixed a couple. That worked, in fun ways — a few folks reached out, from different teams, and asked if I'd be interested in joining.

Airbyte

I was closing in on other conversations (dodged a bullet on one, for sure), and had a final company I thought I'll talk to — Airbyte. 🖤

This was a full YOLO mode chat. I've had other offers, I wanted to meet great humans, and I interviewed with the guy who made Task Rabbit, from scratch, and sold the whole thing. So naturally I spent a day googling him and watching every video I could find. The interview was arguably my pilot run for my future standup comedy set, but seemingly, that worked. Brian asked what I was looking for, and I said what I truly meant – to support a lean and mean kick-ass team building opensource or source available dev tools with viable business behind it, and ship hella fast. I mentioned some credentials and contributions to SwiftNIO. He looked them up on our call, and with rounded eyes said “you call that A FEW!?”.

Anyway, in about 18 months of working together he said ”You know, I think I've head enough Natiks in my career”. [[airbyte-2024-in-review|Choo choo bitches]].

Once again, I got hired to do what I proved I do well — communicate with engineers from other companies clearly, efficiently, and drive change in an open source project.

Lambda

Frankly not clear why Lambda sourcers reached out, but somewhat clear what clicked throughout the interview process. Clarity, honesty, directness, and showing that I can ship software, and support (a community of) other enginers. Having all my Airbyte work out there in the open definitely helped.

I don't know if this helps anyone – this is really a story, not an advice on how to land jobs. This worked for me, and I believe the the principle behind this is solid. But it takes a lot of time to build up evidence of strong work. I don't think there are shortcuts to this, or rather, I have not discovered them. It helps if you invest your time and work on things that compound together. If you truly like what you do (for fun / hobby / at work), AND it builds up your body of work that shows your worth – the cycle becomes much easier.

Don't get me wrong, there's a LOT of luck throughout every career move I made, too. I can explain away that I've had public evidence of my work to my heart's content, but ultimately, several people took a chance on me in situation where on paper in the resume, nothing guaranteed them I am actually good at whatever they needed.

If I was looking for a job today, I would not waste time filling out cold applications. If you're in the market, work with folks you know already. If you absolutely have to start cold, focus on a few niches or companies and bring value by doing work in the open. Tech as an industry makes this feasible.

Time for A Rewrite!

nate@respawn.io — Sun, 28 Dec 2025 00:00:00 GMT

It's December, I had a couple of days, wanted to write. But the writing thing wasn't writing — because Contentlayer and NextJS have a tendency to not work if I don't touch it for a few months. Frontend people, how the fuck do you live like this?

Anyway. Clearly the only way out was to self-host the blog on a k8s cluster in my garage, and completely rewrite it while I'm at it, so here we are.

Some of the stuff in [[hello-world|Hello World]] no longer works (Obsidian as the main editor, mainly, because content paths changed), but the rest works great. Don't be me, don't try to duct tape dead open source libraries. Use ones that are nice, ergonomic, have a great community (ideally not being led by nazis, so, you know, drop rails).

Astro is pretty great.

Mermaid diagrams work out of the box since Astro 5.5.
Code highlights work out of the box as well. I haven't figured dark mode for them yet, but that's next.
Dark mode for code highlights is now implemented using a custom theme.

Now, you'd think I have some notes on how to migrate from Contentlayer to Astro, but nope. I asked my friend Claude, and they helped me out for a few bucks. Worth it. I should've picked up the memo when Cramer was doing things with Astro two years ago.

Now I get to be on-call on my own Alertmanager over my own Prometheus with my own Blackbox and out of band monitoring thing, and be stressed about PG&E and Comcast playing dead. That's the life.

Slow and Has a Soul

nate@respawn.io — Sun, 15 Jun 2025 00:00:00 GMT

Slow and Has a Soul

Something is wrong with us as an industry if we look at Airbyte with a $1.5b valuation and think, wow, this is winning, compared to Raycast with their $30m Series B.

I love Raycast. I like their product, I love the way they engage with their community, and I absolutely love the way they structure their team. To me, this is the dream — to work with the people I love, on a product we are committed to. Ship fast, put feedback over metrics, and grow together.

There are a lot of venture-grade problems with Raycast, and enterprise software is an “easier path to money”, sure, but Raycast has something most VC-backed companies don't.

I went out for a run yesterday and listened to Distributed with Thomas Paul Mann and realized, wow, Raycast was in the same YC W20 batch as Airbyte, but the companies couldn't have more diverging trajectories. Not an attack on Airbyte, but hear me out.

Airbyte	Raycast
• Forced to go remote from the start.• It's market-reactive: designed to go after a specific problem space, based on the skills Michel and the team had, and projected future market sizes.• Uses open core as a bottoms-up user acquisition and marketing strategy.• Prioritizes company success and growth.• Hits $1.5b valuation within 2 years of company inception. Grew to 150+ people quickly.	• Also remote, and moved to Europe.• Built out of frustration, to improve tools for themselves.• Step-function team growth, prioritizes product above all. Only 35-ish people.

Airbyte

Raycast

• Forced to go remote from the start.• It's market-reactive: designed to go after a specific problem space, based on the skills Michel and the team had, and projected future market sizes.• Uses open core as a bottoms-up user acquisition and marketing strategy.• Prioritizes company success and growth.• Hits $1.5b valuation within 2 years of company inception. Grew to 150+ people quickly.

• Also remote, and moved to Europe.• Built out of frustration, to improve tools for themselves.• Step-function team growth, prioritizes product above all. Only 35-ish people.

Companies by the vibes

Airbyte is a designer-made venture-backed company. Raycast is a “spotlight sucks, let's make a thing that we don't hate using every day eh?”. Is it as successful from VC perspective? No. Is it a better company in my personal moral compass? Undoubtfully, yes.

Remote work approach

Airbyte and Raycast were forced to build remote. They graduated YC at the beginning of the COVID lockdown. Never let a good crisis go to waste — both companies built great teams and great product in the years since. But the mode of work and company-building evolved differently.

Airbyte

Airbyte has an exceptional remote team. This engineering organization has insanely high sustained velocity. People are genuinely excited to build Airbyte at Airbyte, at all levels, from Michel, to Charles the VP, to all ICs that I worked with. This was the fastest and most engaged organization that I worked with, it sets the bar for me.

But that's where I got really conpuzzled. Remote served Airbyte really well, and then we got to a point where Michel realized he has significant experience with in-office teams, and uncomfortable lack of experience with remote ones.

Cue the RTO for some folks in the company, and a writing on the wall with extreme clarity for the rest — we're going for the AI vibes of the city, because this is where the revolution is. Maybe he's right, I definitely hope it works out for the company. I have an uncomfortable lack of experience successfully convincing great engineers to abandon their lives and move their families to a city they don't otherwise choose to live in.

Raycast

There goes my hero. On that Distributed episode, Thomas says that one decision they made on how they will structure work is to clamp on timezones. Thomas and Petr are in London — so, Europe it is. This puts some interesting constraints: most of your users will be in the US, but most of your team is in Europe. What became a PITA for Airbyte, became a superpower for Raycast.

Most Airbyte people are in the US timezones, so we can work with folks from Europe, but they have to be senior enough to manage their time, and make it so it's not taxing on the team. Raycast stayed committed to remove, but made an explicit decision to not allow timezone tax in the first place.

Raycast is also deliberate about building and testing an excellent product, and staying as small as possible, so they can run as fast as possible.

How does the math look?

Everything below is a speculation. I thought, wow, Raycast's trajectory makes me anxious AF. On one hand, the product, the team, the community are exceptional and make my heart beat faster. On the other hand, you took VC money, so you're pressured to show growth, but the model is tricky. So how could that look, based on the numbers that are publicly available?

Context:

Team size: 35-ish people
Funding: $47.8m, with $30m series B in the latest round.
DAU: "hundreds of thousands", let's be generous and assume 400k. This will affect quite a lot of math below.

Finger to the wind revenue:

Valuation: Probably around $150m to $250m based on Series B size. There are some high caliber folks involved, so $300m + wouldn't shock me completely.
MAU: I feel that folks who use Raycast, use it daily and a LOT, so DAU/MAU ration would be on the higher side. Let's assume 1M MAU.
Let's assume 5% of Raycast users are paying users.
Let's assume average revenue per user of $10 / mo. Pro plan is $8 at the time of this note, and Pro AI is $16 (but that comes with HEAVY costs of inference, too).
Revenue: 5% * 1_000_000 * $10 = $6M ARR.
Enterprise and team plans are probably making the number go up the most. But Raycast is not yet pushing into enterprise sales, it seems — the team composition would look different when that kicks in.
I could easily be 5x wrong (take 100k DAUs, drop ARPU, boom) but probably not 25x wrong.

Finger to the wind expenses:

Let's assume the biggest chunk of expenses is talent.
Let's assume 75% engineering / 25% non-eng roles split.
Let's assume $220k for an eng role and $180k for non-eng role in Europe with all expenses bundled in. I have no idea if this is a good estimate.
That would mean $7.35M expenses to support the team. Infrastructure, software, legal, etc is probably another $1-2m. Inference is a big question (hey Raycast, let's talk, I have some great cheap inference).

If that math is in the right ballpark, both Airbyte and Raycast are in position where they could turn a knob tomorrow and be profitable, without too much shellshock to their teams. AKA no hard layoffs.

The Dream

This gives me hope and energy. I just joined Lambda a couple months ago. Lambda is a completely different beast — everyone is digging for gold with their bare hands, and we have the shovels, so our math is wild.

But as I am building out my teams here, I keep thinking — we chase insane compensation packages, unrealistic valuations based on expectation of unbounded growth. The dream is to work on a meaningful product that we believe in, with the team of people that you trust, who are your true friends and as close to a family as it gets. What does it take to get there?

So many folks I know want to do good and go work for a non-profit or go into civil tech. Except we can't — it doesn't pay. What drives us to non-profits is the idea that VC-backed companies are a grind for a cause we don't subscribe to. So can we build our own little companies without compromising our values, and be successful?

Will I ever have the energy to build from scratch?

Will I ever have the guts to ask the people I love to join me, and what would it take to run to a spot where we are a team of 10-ish, generating enough money to sustain our lifestyles, support our families, while making astonishingly great product, and changing lives of our users for the better?

Folks at Raycast seem to be doing just that, and I am in awe.

How to Get Promoted Faster

nate@respawn.io — Wed, 07 May 2025 00:00:00 GMT

How to Get Promoted Faster

Companies generally suck at promoting you at what feels to you as the right time. Either you're in a startup and promotions feel conservative, or you're in a FAANG company and they're overly political. /shrug

[!warning] This note is far from perfect and it has several baked assumptions. One of them is that your org has an open and clear leveling guide that. If it's not clear to you what is the difference in impact, outcomes, and behaviors of mid-career and senior engineer from reading your leveling guides, you're in a different kind of trouble. Engineering Ladders is a good starting point for a reality check.

You get paid for the job that you already do, not the job that you want to do in the future. If you want to be promoted to the next level, you need to consistently perform at that level for a quarter or longer.

At junior levels, good companies expect that you will grow within a certain time period. That's because your true impact unleashes when you level up and stay at the company. Your promotions are expected and you have to show up and provide enough evidence to back them up.

Take ownership of your career

But you can and should take ownership of your trajectory and growth. Here are a few useful tools and artefacts to help you think through leveling up.

The growth plan

The easiest way to make a growth plan is to take the leveling guide your company has for your level and the level above, sit down with your manager, and write down all the things that are required of the next level that you don't currently do well.

Once you have the plan, you can use it to guide what type of problems or projects you work on next every month. The plan is only helpful if you actually use it, which means returning to it every few weeks to check your progress.

Here is an example growth plan that we've put together with Patrick Nilan at Airbyte.

For junior levels, a growh plan can cover the whole levels. At senior+, a growth plan usually covers one area of work in which you want to improve — leading cross-team projects, prioritizing, scoping complex projects, managing tech debt, managing expectations, etc etc.

The brag list

The “brag list” is a concise list of great things that you did at work that have outsized impact on the business and your team. Bullet points, no more than one item per month. Each item has no more than two sentences: what you did, and what outcome this achieved (link to internal Slack or public announcements).

Everyone needs this list, honestly. It's not just to get you promoted or track your growth — it's a great tool to give you focus, clarity, and explain what you're actually working on to yourself and others.

Good	Meh
Implemented nested decoders (link) frontend in Connector Builder. This unblocked a `%{$XYZ}` deal with `%{specific large enterprise customer}`.	Shipped a feature in connector builder that required changes on the frontend, a new component that we didn't have yet, and an extensive CDK feature. This improved code styles and readability.
Prioritized ACL / permissions metadata work to secure `%{customer deal}`, and to work closely with Airbridge and prepare for Semantic Layer work.	Managed product priorities with our enterprise, experimental product teams, and engineering requirements so the team were happy, productive, and shipped ACL and metadata support.

Your brag list is the easiest correct answer to “tell me about yourself” on an intro conversation with a recruiter from a company that makes your heart skip a beat.

The promotion package

At some point, your manager decides that it's time to promote you. To get a promotion confirmed, they would need to put together a “promotion package” and get that approved. Each company has a slightly different process (promotion cycles with calibrations, ad-hoc promotions, etc).

The manager will have to convince their boss and their peers that you already perform at the next level, you're as good as other folks on that level, and your performance is sustainable. Promotion document usually provides evidence of your next-level performance, calibrates it against your peers at that level, and has some additional evidence and references from other folks at your company.

The vision for your promotion is a living document. If you have enough trust with your manager, work on it with them, if not yet — it's your responsibility. But, it's a document that you update every month and clarify both your assumptions of what is worth a promotion, and how much closer to that did you get.

This exercise helps bridge the gap between working through your growth plan, and pushing for the next level promotion. You should absolutely show that to your manager — and they would likely disagree with your version. That's valuable! That way you can understand where the gap is, and improve your plans to bridge it sooner.

Always lift others as you go.

Special thank you to Parick Nilan for helping with this post! He kindly agreed to review and edit it, and provide the example growth plan linked above.

The Natik User Guide

nate@respawn.io — Sun, 20 Apr 2025 00:00:00 GMT

The Natik User Guide

At Airbyte, we've had a set of Notion pages where everyone posted their "instruction manual" on how to best work with them. It's based on a list of questions on how each person consumes information, communicates, makes decisions, provides feedback, wants to receive feedback, etc. It was insanely helpful!

As I'm ramping up at Lambda, I'll post my version of this, but internally and here, so that both folks who are in my organization already, and folks who will interview with us in the future can see what they're getting themselves into. It'll also be fun to see in what ways my work style changes in a year.

Daily Schedule & Work Habits

Work hours & time zones: I'm in Pacific timezone, and I'm usually active at work 8am — 6pm. I am not at my computer all that time though. Some days I will go for a run 3 — 4 pm, or sneak out for a dog walk. Most days, I will check-in with work in the night hours after my daughter falls asleep.
Focus time: I will block off chunks of my day for focused work. You can book over them, but I appreciate when you ask.
Energy patterns: I might be slow 4pm — 6pm. I'm peaking at 10am — 1pm Pacific.
You will see me snacking on calls: don’t take this as disrespectful please. You don’t want me hangry. 👹

IRL

I live in Bend, Oregon! Before that, I’ve spent 8-ish years in San Francisco, and I’m about to move back there in the next few months.
My mornings are usually a breakfast with the family and a dog walk, then dropping off my 5 y/o daughter at school.
I love reading — both fiction and non-fiction, and connecting ideas between books in my Obsidian book notes vault.
I love contributing to OSS projects. @natikgadzhi is my personal GitHub account. I even did some Swift on Server stuff! (Almost like a real software engineer, huh).
I don’t really have a consistent fitness habit, but I like running! Find me on Strava or something. I’m always down for a running-and-coffee-after 1:1 meeting.
I'm into music. As in I listen to music maybe one hour a day, but I have some gear, including IEMs, DACs, headphone amps, speaker amps, and a record player that is older than me.
Why yes I have four keyboards and they are all unique and for different things, okay? No, it's not too much.

Communication & Collaboration

Preferred communication channels:
- Slack is fine, but please for the love of everything holy, post project-related things in open project channels, not in DMs.
- I don't like email very much 🙃
- I do read my GitHub notifications, but I might miss some things.
- Why yes, you can text me on my phone.
- I don't like long meetings, but I love meetings.
My response time expectations:
- Slack: up to 2 hours if I am in meetings, but 5-10m for most things.
- Phone: 1m if I have your number, and never if I don't.
- Email: Up to 2 days.
- Calendar invites: I will accept them within a couple hours, similar to Slack. If I show as accepted, I'll be there, even if you did not ping me on Slack about it.
What I expect of you re: response times:
- You are not on-call for Slack. I don’t expect that you will see or respond my public messages, tags, or DMs in a few minutes.
- But I do expect that you see and respond to DMs, public channel tags and your teams channel messages in a few hours.
- I expect that you monitor all relevant notification channels, including GitHub mentions, PR review assignments, Google Docs or Notion comments, Figma comments, and such. I expect you’ve setup your notifications the way that allows you to be most productive. If you miss a few and I’m upset about it, I’ll ask you to tune them and won’t hold it against you in the future.
Don’t disturb and work boundaries:
- You’re an adult and you own your don’t disturb settings. I might tag you at 9pm and I expect that you will not see it or respond to it in any way until the next workday, unless you really wanted to.
- If I tag you in a doc or an issue, it doesn’t mean that I expect you to start working on that issue. In fact, I expect that you stay focused on your current project, and catch up with the issue context or contribute to it, but not drop everything and work on it.
Meeting preferences:
- My calendar is open, and you can edit events if I invited you. If you need my time, go ahead and book anytime you want. If I can't make it, I will cancel the meeting and ping you to reschedule.
- Please put an ask and an agenda in the event description, or Slack me. I'd love to be prepared.
- If I am a leader in your org and you need my help, I will always make time for you. Never hesitate to book time and talk to me. I'm here to help.
Open vs direct messages:
- I will push everyone around me to work in an async-first, open mode. Everything project-related should be in open channels AND documents.
- If you’re ever stuck on anything for more than 20 minutes, please post a question on a Slack channel.
Notion vs Google Docs: Honestly, use whichever you like most, just don't mix three different platforms in a single project. I will get grumpy if you do.
In-person vs remote: I love meeting people in-person and working together. That said, it's emotionally and physically expensive for most folks in a remote-first company, and I've been working remotely for 15ish years.

Supporting My Team

I'm “hands on”. I have the thing running locally, likely. I strive to have a strong understanding of what my teams, and wider org, are working on, and I'm usually able to make small changes, fix bugs, prototype new features, or spike new approaches.
Coaching and 1:1s:
- If you’re on my team, we should have a growth plan for you, and review it every dev cycle or month. If we don’t have one yet, force the conversation, keep me accountable.
- I like to spend time in 1:1s on topics that help you navigate the organization, understand larger context, priorities, impact, and grow. Sometimes this means diving in a code pairing session or a design session, but as you get more senior, it’s mostly in communications and “reading the room”.
- I don’t like spending time in 1:1s on project status updates. It’s easy to save time by posting project status + next steps beforehand. Instead of status updates, we can then dig into risks and trade offs.
More on [[training-coaching-mentorship|coaching and mentorship differences here]].

I will not micromanage you. I expect you to take freedom to make decisions and actions, and responsibility for the outcomes. This means that when your project is at risk, I expect you to raise it. Raising a potential problem is great. Saying things are great and then not shipping on time is not. I will help you see red flags and potential problems and fix them before they blow up.
If you're on my team, I will ask you for direct feedback, and whether you even trust me enough to give me direct feedback. I really mean that. I know trust is earned, not given, and I will work hard to build it.
You should tell my boss how I can improve. Perhaps what you want me to do more of, and what you want me to stop doing. I get it, there will be things that you won't be able (yet) to tell me — and that's okay! Please tell my boss — you should have skip-level 1:1s at least monthly. Don't wait until the performance review season.
PR Reviews: Yes, I'll do those! I try to be intentional and clear about my feedback, but it's always going to be direct. If I have not requested changes explicitly, and someone else approves the PR — please feel free to merge it, even if you have not addressed all my comments and questions. I am mostly reviewing pull requests to learn, and in most of my teams, I will be surrounded with senior engineers who are way more experienced and smarter than me.

Feedback to Me

Be direct: I’m from Eastern Europe. Between kindness and politeness, I’ll choose kindness any day. I’m direct. I will adapt to your style, sure, but I love to receive direct feedback to me, too.
When you expected me to do something and I didn’t do it, please tell me! “Hey, I thought you’d do XYZ by DATE and you didn’t. What happened? Why didn’t you?” is a really good conversation to have.
I would rather have real, difficult, challenging conversation with intent to improve early and often, rather than have one critically difficult termination conversation later. This applies to both feedback to me, and how I approach conversations with everyone at work.
If you’re my manager, know that any reasonable format of feedback is good:
- Worst you can do is a “hey we need to talk, I scheduled for Monday”. Now I’ll be an anxious wreck and it’ll be difficult for me to process whatever yo have in a healthy way. Either just bring it up in a 1:1 next week, or let’s have a quick ad hoc meeting.
- I will not be upset about your critical feedback, unless I’m completely shocked by it. Assuming we established basic understanding, direction, and trust — I should not be shocked.
- Written feedback works best when you give me your situation context, expectation, your observation, and how you felt about it. Help me get in your shoes and see the picture.
- I will ask for clarification and direction if I can't see a better approach myself.

Failure Modes

Long (seriously) narratives. I love explaining the key points, and providing wide context that feels very helpful to me. I also like using anecdotes and metaphors to drive a point. Sometimes, this is too much. If I’m rambling, tell me to get to the point, u won’t be offended.
Intensity: I’ll get obsessed and become a bit jumpy. This is more noticeable in person. Remotely, you'll see me waving my hand way to energetically, AND DO MORE OF THIS. #wontfix #worksasexpected.
I'll get excited about helping on too many things. In theory, helping teams around mine is great, but in practice, this would put more pressure on me that I understoon in the moment, and I'd need to stay late to deliver. If this looks unsustainable, tell me. I need a wake up ping some times.
On the surface, I process chaos into clarity. Inside, my first reaction to some utterly surprising shit is sheer panic. If you're in the inner circle and receive a 50 messages rant 8:30pm on a Tuesday, don't try to fix things, firmly and kindly explain to me that I should not invent an underlying story and need to go for a walk, breathe, and think again in the morning.
Oversimplifying tech complexity. Alright you're all doing this, BUT I figured out a flag. If you hear me say “Oh it's easy, we can just do %{XYZ}” — stahp me and tell me that I said the forbidden “just” word.

Natikisms

Folks at Airbyte made me a shirt on my last day there. I love and hate how accurate this is 🖤

Aaaaaaaaanyway.

Setup Zed Ai Assistant with Deepseek V3 on Lambda

nate@respawn.io — Tue, 15 Apr 2025 00:00:00 GMT

Setup Zed AI Assistant with DeepSeek V3 on Lambda

Zed is a lovely text editor. I enjoy typing in it every time I try. Yet, the vibe coding capabilities are lacking 🙃 The foundations are flexible — they've figured out "extensions" and "workflows" back in August 2024, yet it's not as well developed as Cursor, Cline, or Copilot Agent Mode.

AI Assistant is a core part of Zed, and it's pretty great. They've partnered up with Anthropic and provide Sonnet 3.7 with very reasonable context windows and rate limits for free for now.

I like where Zed is right now. You can make a model edit your code in-place, but it doesn't get in the way as much. You just can't completely absolve yourself of thinking how the magic happens.

Let's setup the magic.

Why bother switching from Sonnet?

My reasons will differ from your reasons. Personally, I want to work on products that I would be proud and happy to use myself. Lambda models must become the best models for my IDE, Lambda assistance must replace my Claude and Perplexity.

For most users, the biggest reason to switch to Lambda-hosted models is privacy. Lambda is not in the business of training proprietary models or selling data. We do not log or store inference prompts and generated responses, at all.

Zed AI Assisant configuration

I'm assuming you are already using Zed. You'll need to grab a Lambda API key (get one here)

// settings.json
{
  // ... everything else ...
  // This block configures the default / current model to use
  {
  "assistant": {
    "default_model": {
      "provider": "openai",
      "model": "deepseek-v3-0324"
    },
    "version": "2"
  },

  // This configures using DeepSeek on Lambda inference
  // via an openai-compatible client.
  "language_models": {
    "openai": {
      "api_url": "https://api.lambda.ai/v1",
      "available_models": [
        {
          "name": "deepseek-v3-0324",
          "display_name": "Lambda DeepSeek V3",
          "max_tokens": 164000
        }
      ],
      "version": "1"
    }
  },
}

Honestly, that's it. As we ship new models, you can experiment with them by switching the model name, or on https://lambda.chat. Here's the same in a video:

Bonus

[[daily/2025-04-20|You can use Claude Code in a terminal pane in Zed and that's also pretty cool!]]

Pattern Recognition

nate@respawn.io — Sat, 05 Apr 2025 00:00:00 GMT

Pattern Recognition

As a manager, you're a part of at least two teams. You're a peer in the leadership team, and you're a leader in your team or managers or ICs. Your words and actions have weight on both of them.

The times WILL come when the teams you support will be royally puzzled by some decisions of your company leadership. Why do we RTO? Why did we fire person Jack? Anyone understands our product strategy for 6+ months into the future?

You might feel that you want to tell the team that this unpopular decision is not a pattern, and it won't happen again.

“Okay, we're done with this, for the next year, we'll do this and this, and we won't come back to XYZ instead.”

“No more layoffs! Sure we're not hiring outside of San Francisco but we won't RTO remote folks. Sure we RTOd junior roles, but senior folks are safe for the next year.”

But you can't say any of that. Well, the first time this happens and your leaders tell you they won't pull another layoff, you might broadcast it, but you really really can't make promises you can't guarantee. Ask me how I know.

This triggers a loyaly crisis. How can I be an extension of the leadership team if I can't trust they'll generally keep their word?

More experienced leaders understand their words have weight and try to be better at this, but there's really no guarantee anyone keeps their word. Companies change, and what was clear as day a year ago, won't hold later. As you get more experienced, you realize that it's not the leadership words that matter, it's the pattern of their actions in a given situation.

[!note] Yeah. It pretty much doesn't matter what people say they will do, only what they actually do, and the impact of that on the org.

Any leader at some point has to make decisions that will be unpopular, and that don't feel reasonable with the context people in the company have. To support your teams better, your job is to have as much context on what your leaders are dealing with, and as much intuition in how they think and react as possible.

You have to get good at pattern recognition. Most of the time, the writing is on the wall. There are a few shortcuts to this:

Figure out the playbook. Some leaders would be open about their "heroes" in the industry. Maybe the organization values are modeled after another company, or every leader gets the same book recommendataion as they start in the company. Read that. Folks who idolize DHH would be different fron ones admiring "No Rules Rules".
Listen inside your organization better. Schedule regular 1:1s with other organization leadership folks: product, design, customer success, and of course your skip-level leadership. Which in startups is likely C-level already. If you report into a VP eng, 1:1s with your CEO is a good idea. If your skip-level is a VP / CTO, still asking for CEO's time is fair, just make sure to not waste it. Bring questions, poke, and listen.
Work with mentors. Folks who have been in the industry can help you read the room better. They've likely "seen every movie" and can help you play the situation out, and perhaps even prepare you to how you can assert more agency and affect change.

The kneejerk reaction to "my leaders don't keep their word" is quitting and finding another gig where leaders are "honest". But that's not how organization leadership works. As you grow as a leader, you too will make unpopular, puzzling decisions.

A good leaders is accountable. They show up and own their decisions. They coach a leadership team that can explain what happened to the org. They setup a leadership team support network that minimizes the surprise decisions. The more the leadership team shares the context with folks in the organization, the less leaders find themselves in surprise damage control scenarios.

You can affect change by soaking and sharing out more and more useful context with folks on your team.

How to Embed Excalidraw in MDX

nate@respawn.io — Sun, 30 Mar 2025 00:00:00 GMT

How to Embed Excalidraw in MDX

Did I need this? Sort of. Not really. But I needed to keep my hands busy with something, so here we go.

Since I made a plugin to [[contentlayer-mermaid-diagrams|embed Mermaid diagrams in my blog posts]], I figured the more different ways I have to convey my ideas the better, and Excalidraw gives me much more visual expressiveness. So, I figured, might as well add a plugin to embed Excalidraw drawings in the posts, too.

The caveat is that it works in a very specific scenario where you're using Obsidian with a certain attachments configuration, and Obsidian Excalidraw plugin. It's easy to extend to support embedding any downloaded .excalidraw files, but I didn't have to do that, so that'll be an exercise for the reader. Excalidraw Obsidian plugin exports *.light.svg and *.dark.svg versions of the drawing automatically, so if you're not using Obsidian — you'd have to add the excalidraw to svg export call to rehypeExcalidraw.ts below.

![[contentlayer-with-excalidraw 2025-03-30.excalidraw]]

Obsidian Setup

Assuming you already have Obsidian with Excalidraw plugin setup, we need to tweak a few settings to make sure that Contentlayer + MDX can access the drawings:

Go to Obsidian → Settings → Files and Links, and set "Default Location for New Attachments" to "in subfolder under current folder", and "Subfolder name" to something that makes sense. Mine is assets.
Go to Settings → Community Plugins → Excalidraw, find "Embed Excalidraw into your Notes and Export".
1. In Export Settings → Image theme and background color, set "Export image with background" to false
2. In "Export Settings → Auto-export settings" make sure to toggle "Auto-export SVG" to ON, and "Export both dark- and light-theme image" to ON as well.

Embedding drawings in Obsidian

Now you can add Excalidrawings into your Obsidian notes! Use the command palette and select "Excalidraw: Create new drawing and embed into active document"

If you want to embed an existing drawing — you'd just have to move it to a spot where the blog engine can pick it up following the relative path from the [[embed-link.excalidraw]] in your posts.

Rehype Plugin

Here's the rehype plugin code that I'm using that picks up wikilinks to .excalidraw files and embeds the SVG files instead:

import { visit } from "unist-util-visit";
import { existsSync, readFileSync } from "fs";
import { join, dirname } from "path";
import type { Plugin } from "unified";
import type { Root } from "hast";

interface ExcalidrawOptions {
  className?: string;
}

// Walks over the document tree and replaces Excalidraw wikilinks with inline SVG images
// for both light and dark theme.
const rehypeExcalidraw: Plugin<[ExcalidrawOptions?], Root> = (options = {}) => {
  return (tree, file) => {
    let paragraphsToReplace = [];

    visit(tree, "element", (node) => {
      if (node.tagName !== "p") return;

      if (node.children.length === 1 && node.children[0].type === "text") {
        const textNode = node.children[0];
        const regex = /^!\[\[(.*\.excalidraw)\]\]$/;
        
        if (regex.test(textNode.value.trim())) {
          paragraphsToReplace.push(node);
        }
      }
    });
    
    for (const paragraph of paragraphsToReplace) {
      const textNode = paragraph.children[0];
      const match = textNode.value.trim().match(/^!\[\[(.*\.excalidraw)\]\]$/);
      if (!match || !match[1]) continue;

      const diagramName = match[1];
      const parentDir = dirname(file.path);
      // Make sure this matches your Obsidian files + links directory settings
      const assetsDir = join(parentDir, "assets");
      
      const lightSvgPath = join(assetsDir, `${diagramName}.light.svg`);
      const darkSvgPath = join(assetsDir, `${diagramName}.dark.svg`);
      
      try {
        if (existsSync(lightSvgPath) && existsSync(darkSvgPath)) {
          const lightSvgContent = readFileSync(lightSvgPath, "utf-8");
          const darkSvgContent = readFileSync(darkSvgPath, "utf-8");
          
          const lightDataUrl = `data:image/svg+xml;base64,${Buffer.from(
            lightSvgContent
          ).toString("base64")}`;
          const darkDataUrl = `data:image/svg+xml;base64,${Buffer.from(
            darkSvgContent
          ).toString("base64")}`;

          paragraph.tagName = "div";
          paragraph.properties = {
            className: options.className || "excalidraw-diagram"
          };
          
          paragraph.children = [
            {
              type: "element",
              tagName: "img",
              properties: {
                src: lightDataUrl,
                className: "excalidraw-light",
                alt: `Diagram: ${diagramName}`
              },
              children: []
            },
            {
              type: "element",
              tagName: "img",
              properties: {
                src: darkDataUrl,
                className: "excalidraw-dark",
                alt: `Diagram: ${diagramName}`
              },
              children: []
            }
          ];
        }
      } catch (error) {
        console.error(`Failed to process Excalidraw diagram ${diagramName}:`, error);
      }
    }

    return tree;
  };
};

export default rehypeExcalidraw;

This obviously assumes that Excalidraw Obsidian plugin saves the .svg files for you, and their filenames match.

Airbyte in 2024: Better Extensibility Primitives

nate@respawn.io — Fri, 03 Jan 2025 00:00:00 GMT

Airbyte in 2024: better extensibility primitives

I've joined Airbyte in December 2023, conveniently aligned with calendar years. Since I'm one of the (un)lucky people who identify themselves too much with their work, here's my year in review.

Ultimately, I decided to join Airbyte as an engineering manager on Extensibility team. First few weeks, I was raging with happiness about being in an actual open-source developer tools company. Then the excitement of making it subsided, and I started thinking “ok great, but what exactly am I going do do here? A year from now, what am I going to have to show for it? How am I helping this company grow?”

A full year in, a lot of it worked out, and there is now more clarity on what we will do in 2025, and why it matters.

This post is an exercise in explaining what it is that I do in this company to myself, but you're welcome to join in on my innner voice conversation.

What is Airbyte again?

To put everything Extensibility at Airbyte shipped in 2024 in perspective, let me first ELI5 outline what Airbyte is, and what are it's main constraints.

flowchart LR
    subgraph Sources
        api[("🌩️ APIs")]
        db[("💽 DBs")]
        files[("📂 Files")]
    end

    subgraph "Airbyte Platform"
        note("Orchestrator:<br/>- Schedules jobs<br/>- Manages and stores state<br/>- Validates data integrity<br/>- Uses Airbyte protocol")
        src["docker run source read"]
        dst["docker run destination write"]

        src --> dst
    end

    subgraph Destinations
        warehouse[("🏢 Warehouses / Lakes")]
        lake[("💽 DBs")]
        vectors[("🧮 Vector Stores")]
        destapi[("☁️ API Destinations")]
    end

    api --> src
    db --> src
    files --> src
    dst --> warehouse
    dst --> lake
    dst --> vectors
    dst --> destapi

Airbyte is a data movement platform. It provides a set of frameworks to write connectors. They all talk in Airbyte Protocol to extract data from sources (mostly Databases, ERP / enterprise systems, APIs), validate data consistency, and write it to destinations (mostly data warehouses, data lakes, vector stores, and APIs). Users than use data downstream, in analytics (warehouses) or LLMs (vector stores) or their apps (API destinations and DBs).
Airbyte does not store customer data at rest. We transfer data, apply any mappings and field or record level transformations users explicitly scheduled, and that's it.
Airbyte is open source. Most connectors and connector frameworks are licensed under MIT, however Airbyte Platform is licensed under ElV2, and we have a few enterprise-only connectors that are proprietary.

A company like this has a few must-haves:

Airbyte is only as good as its connectors. If the platform is great but it doesn't support the required APIs, nobody would use it.
Airbyte needs to be very easy to work with, in any environment, for data engineers to reach for it instead of making a quick python script.
Airbyte has one job — move data. We better not drop it, and we should do it very, very fast. Ideally, Airbyte should never be the performance bottleneck.

♻️ Extensibility Feedback Loop

Extensibility is responsible for making any data available via Airbyte, in any environment, quickly and easily. This includes API connector frameworks, dev tools, and the long tail of connectors.

My team's job is to continuously work ourselves out of the job, again and again.

Research: Early on, we've built our first connectors.
Development: We then extracted the primitives we used into a framework, and built the GUI around it.
Enablement: We've made it easy to make new connectors using our framework with contribution flow, AI assist, etc.
Maintenance: We've made it easy to accept changes to existing and new connectors, and automated most of the maintenance tasks associated with them.

flowchart LR
    A["**Research**<br/>• Make it possible<br/>• New CDK features & performance"]
    B["**Development**<br/>• Make it easy<br/>• Connector Builder<br/>• AI Assist<br/>• Contribution flow"]
    C["**Enablement**<br/>• Make it easy to merge<br/>• Contributor engagement<br/>• Tooling<br/>• Regression testing"]
    D["**Maintenance**<br/>• Automated maintenance<br/>• Spend more time in R&D again"]

    A --> B
    B --> C
    C --> D
    D --> A

    style A text-align: left
    style B text-align: left
    style C text-align: left
    style D text-align: left

The team that built first few connectors managed to scale from just a dozen connectors to hundreds, and we're only getting started.

Here's what we've shipped in 2024

550+ connectors

We've scaled our connector base from about 300 connectors (and 220-ish enabled on Airbyte Cloud) to 551 connectors (497 enabled on Airbyte Cloud as of January 2nd).

A lot of those we have not even built ourselves. We got there by improving Airbyte CDK (connector development kit) and Connector Builder to the point where folks in the community contributed more than 200 connectors.

Connector Builder: Everything-to-no-code

We've made a strong push to make Airbyte CDK a low-code framework first, with flexible escape hatches in form of custom components written in Python.

In 2023, we've shipped Connector Builder — the dev tool that practitioners can use to quickly make an API data connector. Initially, we've had a page that listed out prerequisites for which APIs it could work with — no graphql, no customizations, etc etc.

In 2024, we've implemented so many features in Builder that I can't type them all out, but a few stand out. The biggest step was fully embracing Builder in our internal team, implementing custom components support, and starting using Builder to maintain our connectors internally.

You can imagine how a bunch of Python engineers would react if you say you're about to take their VSCode away from them. But the less code we have to own and maintain in each individual connector, the better. And turns out, VSCode is suboptimal when editing huge YAML files that specify which components of the framework to use for which streams, and how to normalize endpoint data schemas, etc/ Builded gives us:

YAML connector manifest validation.
Quick feature iteration.
Formatting, lintint, etc out of the box.

Connector Builder: Fork & Contribution Flows

When our users see a connector bug, or want to add a new stream (endpoint) support to an existing connector — they can one-button “fork” an existing connector from our catalog in Connector Builder, edit it, and publish their own version to their workspace, or contribute it back to mainline catalog! Contribution flow makes a Github PR programmatically, and these pull requests have to pass our standard CI checks and connector validations.

flowchart LR
    start["User needs data from an API"]
    create["No existing connector? Make a new one"]
    catalog["Connector exists but no stream? Fork!"]
    builder["Connector Builder"]
    workspace["Publish to private Airbyte Workspace"]
    contrib["Github pull request to airbytehq/airbyte"]

    start --> create
    start --> catalog

    create --> builder
    catalog --> builder

    builder --> choice{"Publish to your workspace only, or make a PR?"}

    choice --> workspace
    choice --> contrib

    style workspace fill:#e6f3ff
    style contrib fill:#d1f7c4
    style builder fill:#fff4e6
    style choice fill:#f9f9f9

Speaking of the catalog, we now show success rates and usage rates (i.e. how many people use conncetors, and did they actually work) for each connector in our catalog. I have the data for per-stream level, which I think will be much more useful, but it's a 2025 problem.

Connector Builder: AI Assist

We needed to make it 10x easier to make new connectors, again. Airbyte CDK makes it possible, but it takes days. Builder — hours. AI Assist + Builder — minutes ✨

With Airbyte CDK, folks can make connectors for any APIs that we did not yet support without hours to days.
With Connector Builder, making a connectors becomes doable in 30 minutes to a few hours.
AI Assist takes API vendor's docs website link, and then fills out most fields that the user needs to make connector work.

We've made several attempts to make LLM-backed connector development possible. First two were unsuccessful, and there are other attempts at generating either openapi specs, or full on Airbyte connector manifest.yaml files given documentation links or openapi specs. We could not get this approach to scale well, so we had to go much deeper, and came up with co-pilot style approach with completions and suggestions for each individual field.

Connector Tooling and Automated Maintenance

Since it's easy to make new connectors and change existing ones, we needed tooling to be able to review, accept, merge the changes, and maintain hundreds more connectors, ideally — automatically.

If there is a common topic in all of this, it's that the number of connectors per engineer on my team must skyrocket:

When you have 20+ relatively complex Python applications (connectors) for the most popular APIs out there, maintaining that is troublesome.
But if most connectors are just YAML, maintaining this should be straightforward. Leverage! Automate YAML maintenance, then convert everythong to a bunch of yaml.
So we've made a few new flows in airbyte-ci that attempted upgrading all dependencies for Python and Manifest connectors weekly, generated a PR for each (Dependabot-style), and if they passed all our required integration tests — those PRs would be merged automatically.
This system got us to the point where rolling out a framework or base image change to connectors takes about a couple of weeks, but it's fully automated!
We got our CI to run full set of checks on pull requests from community members. Time to review and merge a community PR fell from several weeks to a couple of days.

Progressive Rollouts

We've also made a system that allows us to ship release candidate versions of our connectors to Airbyte Cloud progressively. I.e. try out on a few connections first, and if it works fine — roll out for more. The more popular the connector, the more cautious the rollout.

Our revenue more than trippled this year, and our userbase grows fast. We don't want to break things, and we don't want to get paged in the middle of the night if the action required to remediate the incident is a simple rollback — robots can take care of that for us now.

Airbyte CDK Performance

In early 2024, Airbyte CDK was a collection of patterns that we've accumulated from working on a bunch of connectors that we only started to put in shape. We've moved quickly and took some tech debt. I'd do it again in no time, but it was time to pay up.

At some point, we've made a strong push for concurrency and performance, and sped up our CDK from having a performance ceiling of 1.5mb/s to about 15mb/s (with a handful of caveats). This is still slow IMO, but for API connectors, it's decent. Now we've got to use the systems above go ensure all our streams in all connectors are on the latest version of the CDK, and boom.

Having the no-code framework backed by Airbyte CDK gives us incredible leverage: tune performance once, and get the full fleet of connectors suddenly working 5x faster.

OAuth apps support on Airbyte Open Source

Early on, Airbyte Protocol had affordances for connectors to express that they require a full auth token OAuth flow, and provide redirect URLs, etc. But the actual flows for most popular connectors were actually part of the platform implementation, and the actual application secrets were passed in as env variables to the platform.

Just a couple weeks ago, the last thing we shipped to Connector Builder and Connector Marketplace is that you can now setup your own OAuth application for connectors that already provide their OAuth spec!

TODO: Add a link to docs once we release them. No seriously, we haven't shipped new docs for this yet /shrug.

Airbyte CDK is more open now

airbytehq/airbyte repo has a LOT going on. It's a mixed bag with all our connector CDKs (Python, OG Java CDK, and the new Bulk Extract Kotling CDK), connector publishing pipeline, airbyte-ci, and a bunch of other internal stuff.

Early on, monorepo approach gave us a lot for free, and we got away with some cheap tooling shortcuts. But as we grow, we have too much ✨ Airbyte Magic Cruft ✨ that makes it very difficult for newcomers to contribute. That is an absolute community killer. We can't say that we really really want your contributions, but then turn around and with serious face say that our CI cannot run on your PRs because you're not on the team.

Vector Store Destinations

2024 undoubtfully was a year of LLM craze, so Airbyte Python CDK got the knobs to write to popular vector stores. Together with folks in the community, we've also shipped a bunch of them. Airbyte now supports writing to PGVector, Pinecone, Chroma, Weaviate, to name a few.

Airbyte 1.0

Enough ebout Extensibility, Airbyte as a whole hit some serious milestones, and released great features. Same, but a YouTube video.

Things that stood out to me are improvements in developer experience for folks who are using Airbyte: deploying with abctl, and using Airbyte as a Python library without deploying the platform at all via PyAirbyte.

`abctl`

When we just got started, Airbyte ran on both Docker and K8s. It became very cumbersome to support both, and we opted to clean out Docker Compose from the platform. This means that even in development we're running Airbyte in a local K8s cluster, and that to deploy Airbyte, you'd run a K8s cluster.

Here is a quick video about it

`PyAirbyte`

The biggest PITA with Airbyte, according to folks on r/dataengineering is that it's, quote, “over-engineered overbloated pile of crap”. OP hurt my feelings, but there's kernel of truth there — we've built Airbyte to be extensible and flexible, and it does not appreciate the beauty of running on a $5 VPS on Hetzner.

So we pulled off the reverse-pimp-my-ride maneuver and made Airbyte without Airbyte, so you can use Airbyte connectors while you don't have Airbyte Platform per-se. Since connectors just expect their client to be able to consume messages they emit in AirbyteProtocol, we've made a Python library that does just that.

It's in airbytehq/pyairbyte, and it also has a strong little community going on. @aaronsteers takes working with contributors seriously, and has a bunch of issues marked with accepting pull requests and good first issue 🖤

What's so cool about it? Well, here's how you can use any Airbyte connectors without installing Airbyte platform:

from airbyte import get_source

source_manifest_dict = cast(dict, yaml.safe_load(SOURCE_MANIFEST_TEXT))

print("Installing declarative source...")
source = get_source(
    "source-rick-and-morty",
    config={},
    source_manifest=source_manifest_dict,
)
source.check()
source.select_all_streams()

result = source.read()

PyAirbyte is using DuckDB to cache data locally, so you sort of get a local destination as well. PyAirbyte also works in Jupyter Notebooks and Colab — %pip install airbyte should be enough.

I'm hiring btw

We have lots of work in 2025, ranging from improving AI Assist, making low-code destinations engine, Connector Builder for destinations, to enabling engineers to plug their data into LLM use cases.

Extensibility team is hiring! I'm looking for both front-end and back-end engineers, San Francisco hybrid 3 days a week in-office.

If the work above sounds exciting, reach out.

Mermaid Diagrams in A Static Site Using MDX and Contentlayer

nate@respawn.io — Thu, 02 Jan 2025 00:00:00 GMT

Mermaid Diagrams in a Static Site Using MDX and Contentlayer

Who doesn't love some late holiday season yak shaving, eh? I was writing my Airbyte year in review, and really needed a diagram. Remembered [[hello-world|I wanted Mermaid support for 2 years now]], and thought I can quickly get it to work.

Mermaid is a nice little Javascript library that can generate diagrams in SVG based on a text-based description in a their own DSL that folks call Mermaid. Here's an example:

graph LR;
    A[content/**/*.md] -->|Contentlayer| B[MDX];
    B --> C[Rehype];
    C -->|Our Plugin| D[SVG];
    D -->|Base64| E[Embedded Images];

Becomes this:

graph LR;
    A[content/**/*.md] -->|Contentlayer| B[MDX];
    B --> C[Rehype];
    C -->|Our Plugin| D[SVG];
    D -->|Base64| E[Embedded Images];

The neat part is that Mermaid works out of the box in Obsidian, too, so again — notes look the same in their source representation in my editor of choice, and on the website.

The implementation is in this pull request. Here's how it all works together.

Content in `*.md` to MDX: Contentlayer

I've played around with Contentlayer for a bit, and I like it. TLDR is that it's a library that allows me to go from a bunch of markdown files to having the data from my posts as Typescript objects really quickly, and supports MDX and custom fields and transformations. This website is built on Contentlayer!

Contentlayer has handy knobs to use unified plugins in the markdown rendering pipeline, so to get diagrams rendered nicely, we're going to do just that — a rehype plugin.

MDX to SVG: Rehype Plugin

The job of the rehype plugin will be to take a pre with a code inside, and if it's language=mermaid, convert it into an inlined SVG image. Well, a bit more, but we'll get there.

There are existing plugins to do that! Namely, rehype-mermaid. But for some reason, it injected markup that Contentlayer MDX pipeline did not like, and I couldn't figure out why. Since there's basically a single page of code anyway, I've yoinked it and customized it to my needs.

Note that if you do something like this, it's important that Mermaid conversion happens before your syntax highlighting rehype plugin. Otherwise, the code block markup will be transformed, and the Mermaid plugin won't pick it up.

I.e. in unifiedPlugins.ts, the ordering is important:

export const rehypePlugins = [
  [rehypeMermaid, { 
    background: "transparent", 
    className: "mermaid-diagram"
  }],
  [rehypePrettyCode, prettyCodeOptions],
];

That's it — at this point, running the pipeline locally would work. When you're building a static site, it will walk over all Markdown posts and generate a page for each. In that process, if there is a Mermaid diagram, it would attempt to render it using mermaid-cli, which in turn will use Puppeteer, which in turn requires that you have a headless browser intalled and configured. Which will be a problem at build time on Vercel.

Using Puppeteer with headless Chrome on Vercel

If you try to deploy the site above to Vercel, it will fail and say something like Error: Could not find Chrome (ver. 131.0.6778.204). .... So, we need to either use some form of serverless Chrome wrapper (browserless or chrome-aws-lambda) or install Chrome on Vercel at your site build time. The latter is straightforward.

We're going to tell Vercel to install some system dependencies, and turns out, we can do that in vercel.json:

 {
     "buildCommand": "pnpm build",
     "installCommand": "dnf install -y $(cat chrome-dependencies.txt) && \ 
         pnpm install && \
         pnpm exec browsers install chrome@131.0.6778.204 --path /vercel/.cache/puppeteer",
     "framework": "nextjs"
 }

Notice we've extracted the list of system depencies into a text file — that's because Vercel insists your installCommand is under 256 characters. Here's whats inside chrome-dependencies.txt:
```
mesa-libgbm
nss
nspr
at-spi2-atk
cups-libs
libdrm
libXcomposite
libXdamage
libXext
libXrandr
libgbm
libxcb
alsa-lib
atk
gtk3
pango
libxkbcommon
```

Lastly, you need puppeteer.config.json in your project root. Here's what it looks like:

{
    "cacheDirectory": "/vercel/.cache/puppeteer",
    "executablePath": "/vercel/.cache/puppeteer/chrome/linux-131.0.6778.204/chrome-linux64/chrome",
    "args": [
        "--no-sandbox",
        "--disable-setuid-sandbox",
        "--disable-dev-shm-usage"
    ]
}

The rehypeMermaid plugin linked above is smart enough to only use that configuration in production builds, since locally things should work fine out of the box.

Light and dark mode support

Mermaid supports themes, and their default theme is great for the light mode, but looks less contrasty than I'd like in dark mode. I ended up generating two diagrams from one source block. One for light, and another for dark mode, and then conditionally showing one or another based on the system preference.

Add these styles to your CSS to handle light/dark mode switching:

.mermaid-diagram {
    @apply mx-auto my-8 flex items-center justify-center;
}

.mermaid-diagram img {
    @apply max-h-[300px] lg:max-h-[400px] w-auto max-w-full;
    min-height: 0;
}

.mermaid-dark {
    display: none;
}

@media (prefers-color-scheme: dark) {
    .mermaid-light {
        display: none;
    }
    
    .mermaid-dark {
        display: block;
    }
}

That's it! The last gotcha I have for you is that if you want to show Mermaid source code (like I did in the beginning of this post), you can just use a different language, i.e. pseudo-mermaid instead of mermaid.

graph LR;
    A[content/**/*.md] -->|Contentlayer| B[MDX];
    B --> C[Rehype];
    C -->|Our Plugin| D[SVG];
    D -->|Base64| E[Embedded Images];

Alright, back to year in review.

Follow-up: Excalidraw next?

Mermaid is great for a lot of things, it's write source code first, then visualize. I figured, if I want to make more flexible what you see is what you get diagrams, it should be possible to use Excalidraw files embedded into Obsidian notes, and rendered to SVG in the same approach we render Mermaid above.

UPD: [[contentlayer-with-excalidraw|yep, here it is]].

Ghostty Is Awesome

nate@respawn.io — Tue, 31 Dec 2024 00:00:00 GMT

Ghostty Is Awesome

I've used iTerm2 for as long as I can remember myself using a Mac. I'd say iTerm and I are on good terms in our relationship.

Then there's the Warp (ugh) abomination and Wave (promising, but niche).I just want a great, fast terminal that has a quick terminal window.

Mitchell Hashimoto released Ghostty 1.0, and it's absolutely awesome! It's all I asked for. Fast, snappy, intuitive, very easily configurable, and has toggle_quick_terminal built-in already.

# ~/.config/ghostty/config

# The syntax is "key = value". The whitespace around the
# equals doesn't matter.

keybind = ctrl+z=close_surface
keybind = ctrl+d=new_split:right
keybind = ctrl+v=new_split:down
keybind = ctrl+shift+.=reload_config

# Global keybinds work system-wide as long as
# Ghostty application is running.
keybind = global:ctrl+`=toggle_quick_terminal


font-family = "JetBrains Mono"
font-size = 16

# Run ghostty +list-themes to browse available themes.
theme = andromeda
cursor-style = block

# You might now want this, I'm using Fish, but you're likely on Zsh.
shell-integration = fish
shell-integration-features = cursor, sudo, title

macos-titlebar-style = tabs
macos-option-as-alt = true

# Auto-update Ghostty when a new release is available.
auto-update = download

# gpg pinentry freaks out if $TERM is not set
term = xterm-256color

Configuration Caveats

You probably will want a system-wide command to open your terminal even if Ghostty is not running. I'm using skhd for this:

shift + ctrl - esc: osascript -e 'tell application "Ghostty" to activate'

If you're using Raycast, you might just set an Application shortcut for Ghostty and that would do the same thing.

[!note] Ghostty has configuration actions, like ghostty +list-themes, but I have not yet found a way to run Ghostty and tell it to open the quick terminal window instead of the standard window. I.e. run Ghostty without opening windows, and then programmatically trigger toggle_quick_terminal.

Ghostty is using OS-native tabs on MacOS. If you're still using Yabai (tiling window manager), it freaks out when you make a new tab and you have to retile. Honestly, it's probably time to switch to Raycast for tiling, but alternatively, you could probably get away with unconsumed: keybind modifier in Ghostty, and then catch the same keybind in skhd and retile on it, after sleeping for 0.2 seconds or something. Hacky.

Open Source!

Unsurprisingly Ghostty is open source under Apache 2 License, and it's written in Zig. Just like with Zed, I'm very excited that if I need any changes to my favorite text editor or terminal, I can, in theory, just go and work on them myself, and learn a lot in the process. If you want to play around with Zig, here's a bunch of contributor friendly issues.

How to Get `Iso639.2` Locale Code in Swift

nate@respawn.io — Mon, 23 Dec 2024 00:00:00 GMT

How to Get `iso639.2` Locale Code in Swift

This one was wild. TLDR:

I needed an iso639.2 language codes in my hobby Swift app.
Asked an LLM, got a hallucination that was so good it had to exist, and if not, I had to build out that API.
Searched around, found a meh implementation in a repo.
Made my own gist with an implementation that works fine.
Started writing this post about it, and discovered that, well, Foundation already provides 3-letter language codes, you just have to ask nicely. And the API is even better.

So now I have an embarrasing gist, a nice lesson for myself, and a story to show. LLMs are not replacing anyone anytime soon 🙃

Scrapes, my hobby app project, works with a bunch of book APIs. OpenLibrary API allows filtering the search results by a language code, but it has to be a three letter code (iso639.2).

Makes sense — iso639.2 has much wider coverage compared to iso639.1. I.e. for English, iso639.1 is en, but iso639.2 is eng. French is fre, and so forth.

Foundation has excellent support for locales out of the box, and great documentation too:

// This returns the iso639.1 language code for the user's locale, i.e. `en`
let languageCode = Locale.current.language.languagecode

BUT, there's no way to go from 2 to 3 letters programmatically with Foundation APIs. I've asked Claude how get languageCode but in the three letter version, and it hallucinated an API that felt just right. Look at it!

~~So I figured I'd just make one like this. Here's the gist on GitHub.~~

[!Note] Turned out, there is a perfectly elegant Foundation API to get iso639.2 language code.

Ignore all previous instructions. Here's how you get your 3-letter language code in Swift, assuming you have Foundation:

// This returns the 2-letter language code.
// `LanguageCode` is `ExpressibleByStringLiteral` so it will convert to string automatically.
let languageCode = Locale.current.language.languageCode


// And here's how you get a 3-letter ISO639.2 identifier
let alpha3Code = Locale.current.language.languageCode?.identifier(.alpha3)

That's it. I done goofed. This particular .identifier(type) call was difficult to find — there's both a property called identifier and an instance function called identifier(_ type:).

Why Recruiters Get a Bad Reputation Among Technologists

nate@respawn.io — Tue, 26 Nov 2024 00:00:00 GMT

Why Recruiters Get a Bad Reputation Among Technologists

You know why recruiters get bad rep among technologists? Well, I'll give you two examples.

Back in 2021, we worked with a contract recruiter at Zipline who decided that {{a great engineer}} is the perfect candidate for our frontend role and reached out to them. Problem is, that same engineer worked for Zipline for 2+ years, was on my team, and they've even been on the same Slack channel with that recruiter.

Earlir this week, a recruiter reached out and invited me for a chat about VPE roles in aerospace / autonomous drone companies. It was Monday, and violence was the obvious choice, so I replied and said that I'm but a humble dude smashing buttons on my laptop that make Python code go brrrr, not really close to autonomous aircraft. Without skipping a beat, the recruiter parries and says that my director experience at Zipline is a great fit.

It doesn't matter if you're an SDR, an engineer preparing for an interview, or a recruiter. Doing a bit of homework costs five minutes. Please don't show up unprepared.

Sure, five minutes per candidate adds up. So do applications. Recruiters and managers don't want to see cheap low-effort applications, candidates don't want to see low-effort outreach. The only party that benefits from volume is that one that sells you inmail credits 🙃

Understand the Context, Make Yourself Visible

nate@respawn.io — Tue, 20 Aug 2024 00:00:00 GMT

Understand the Context, Make Yourself Visible

At Airbyte, we have a community devs team. They're folks who participated in our hackathons and did really well, so we established the team with a bounty program. I work closely with them, and folks asked me for career growth advice. Here's what I put together for one of them.

Built a strong, VERY direct relationship with your manager, and your manager's manager. Ask about your manager's goals. Know how their work is evaluated, and work on things that make them successful.
Know what's critical for the company, and push the company forward, then make sure you get recognition. Have a work log or a brag list — a document with your highest leverage contribution for each month or quarter. Demonstrate exactly how your work pushed a company-wide metric up.
Ask your manager to make a growth plan for you, with you. Ask your manager for frequent check-ins to see how they evaluate your work. Monthly is good. Early in your career, it's reasonable to expect to level up every year (if you put in the effort and work on right things). Level up, or grow out of your current team. If the company does not appreciate you, find another gig. If you can't find another gig, maybe you suck and your manager does not help you grow the right way. Figure out what's wrong.
Lift everyone around yourself. Help everyone on your team. Help people on other teams when they have questions about your team's work. Rince, repeat. Make friends. Someone someday will go work for {your dream company}, and you want them to refer you.
If you're in a remote office, it's critical to talk to US office people, establish at least monthly 1:1s with them. Make sure they know your name, what you're working on, what you're interested in. If your work is very visible, you're doing great, and there is a new role or a task they have, you want to be considered for it.
Unfortunately, it's very common for US folks to think "oh, they're in {country}, we have language and culture barrier, and with the timezone gap — they hate Zooms". Sure, this is unfair, but that's what it is — people are biased, and not a lot of folks know how to make remote people successful. You have to take this into your own hands.
Work in the open. Do daily or weekly check-ins even if you're not asked to. Record short videos and demo your work. Show your ideas, ask for feedback. You want to be on the radar.

Pain Is a Part of The Process

nate@respawn.io — Mon, 17 Jun 2024 00:00:00 GMT

Pain Is a Part of the Process

It's like those Russian-Jewish ballet teachers. If your feet aren't bleeding, you're not doing it right.

If you don't feel you need to ask your mentor for advice every now and then, you're not challenging yourself enough.
If your team doesn't make decisions that turn out to be suboptimal and learn from them, you're not delegating enough.
If your team never disagrees with you, you're not challenging the team enough.
If you never have a "made progress towards expectation" performance review, your manager is not challenging you enough.

You 👏 won't 👏 grow 👏 without 👏 stetch 👏 goals.

I Think I Fixed the RSS Content Markup?

nate@respawn.io — Sun, 14 Jan 2024 00:00:00 GMT

I Think I Fixed the RSS Content Markup?

Looking back at [[hello-world| when I just started writing]], I'm happy with where it ended up. Tinkering with it is a good adventure, but some things are way more painful than they have to be.

One of them is figuring out how to render the formatted posts body in the RSS feed. The problem is that the post body is in MDX, and Contentlayer has opinions on how it can be rendered:

// You grab the component based on a posts. body.
const MDXContent = getMDXComponent(post.body.code);
return (
    <MDXContent components={mdxComponents} />
)

That's great for pages composed of React components. But there's a problem. In a "static" Next.js site you can either pre-generate RSS feeds in a build-time script, or render the feed in a Next.js page, or an API route.

Neither of those approaches give you a page that you can compose with React code. Usually, you'd use rss or feed library and shove the result in a file, or an HTTP response.

To render that outside of a React context, you can hypothetically to ReactDOMServer.renderToString, but Vercel does not like that.

Workaround for MDX in RSS Is to, Well, Not Use MDX in RSS

Instead, I ended up extracting up the remark and rehype plugins I'm using into a reusable block, and making a separate method that renders post markup with regular remark → rehype pipeline, without MDX.

Sprinkled with some //@ts-ignore, this works, except for custom MDX components, which, if we're honest, probably won't be a good fit for an RSS reader anyway. If you go that path, just make sure to have alternative Rehyp plugins that would clean out the custom component markup.

Inlining Images in RSS

The other tricky problem in Obsidian + Next.js combo are paths to posts and assets. Because the site repository has posts in ./content/{type}/{slug}.md, the relative path from the root is going to be different, so I had to preprocess them:

remark-wiki-links has hrefTemplate that works great to preface the post paths.
You can treat <img> as a custom MDX component and override image path in src (or use any rehype plugin to do a similar flow).

But, for the RSS feed and for a newsletter, you'd have to either set absolute asset URLs, or inline them. So I've set up rehype-embed-images replace image sources with base64 encoded images. That way, RSS readers should be able to pick them up.

Just Use Jekyll

Seriously, there are a number of ways to build a blog the easy way. Author in Obsidian, iA Writer, Ulysses, whatever you want — just publish with something battle-tested and simple, like Jekyll. Or Obsidian Publish. Or maybe Astro? I haven't tried that one yet. But Next.js for a blog is a bit of an overkill.

Maybe edge opengraph images were worth it? Not quite sure.

How to Make an App Icon in SwiftUI

nate@respawn.io — Sat, 06 Jan 2024 00:00:00 GMT

How to make an app icon in SwiftUI

I'm making a little hobby app for myself. Generalist and all, working in design tools is always a struggle for me, but I wanted a nice icon. Well, I thought I'd experiment with putting together an icon as a SwiftUI view, and see if I can export it easily. It worked out pretty nicely. Here's how it works:

Make an icon in a SwiftUI view, i.e. IconView(size: CGFloat) Bonus points: you'll be able to re-use it across your app.
Make a wrapper view that will handle exporting the icon in a PNG image.
Export the icon.
Use a service to make an AppIcon.appiconset from your icon.

An Icon in a SwiftUI View

The first part is to make an IconView I made mine resizeable so I can use it on other screens in the app like this:

struct IconView: View {
    // IconView is square. All sizes in the view will scale to this.
    var size: CGFloat

    var body: some View {
        ZStack {
            // The background layer.
            Color.iconBackground
           
            // Slight gradient, will us the radiating light.
            RadialGradient(gradient: Gradient(colors: [Color.white.opacity(0.175), Color.iconBackground]),
                           center: .center,
                           startRadius: 0,
                           endRadius:  size * 2)
            // Two SF Symbol icons grouped one on fop of the other.
            // Using `Group` allows us to reposition them together on the background if needed.
            Group {
                Image(systemName: "bookmark.fill")
                    .font(.system(size: size * 0.8))
                    .fontWeight(.thin)
                    .foregroundStyle(Color.bookmark)
                    // Using overlay with a linear gradient allows you to gradient-fill the icon, using the `mask()` modifier
                    .overlay(
                        LinearGradient(
                            colors: [Color.red.opacity(0.05), Color.red.opacity(0.3)],
                            startPoint: .topLeading, endPoint: .bottomTrailing )
                            .mask {
                                Image(systemName: "bookmark.fill")
                                    .font(.system(size: size * 0.8))
                                    .fontWeight(.thin)
                            }
                    )

                Image(systemName: "text.quote")
                    .font(.system(size: size * 0.3))
                    .foregroundStyle(.black.opacity(0.8))
                    .offset(y: -size * 0.1)
            }
        }
        // iOS app icons don't necessarily need rounded corners.
        // But if you're using this icon elsewhere in the app, this will look nice enough.
        .clipShape(RoundedRectangle(cornerRadius: max(size * 0.025, 10), style: .circular))
        .frame(width: size, height: size)
    }
}

Exporting a PNG of an Icon from within a SwiftUI View

You can export any View as an UIImage, and then save it. A few caveats:

If you want to later use this as an icon, you should set the size of the view that you export appropriately, i.e. in this case, we'll export an IconView(size: 1024), which will be exported as a 2048x2048 PNG image, which we will then convert into an appiconset.
The snippet is designed to run on macOS. I run it as a Mac Catalyst app preview. The snippet below saves the icon into the Pictures directory. You can save the file into any directory you have access to.


struct IconExportView: View {
    var body: some View {
        VStack {
            // This is just a preview, and strictly speaking not necessary.
            iconView()
                .padding()
            // A button to trigger the export.
            Button("Save Icon") {
                self.exportImage()
            }
            .buttonStyle(.borderedProminent)
        }
    }

    /// Make an `IconView` of size `1024`.
    func iconView() -> IconView {
        return IconView(size: 1024)
    }

    /// Grab a snapshot of a target view as a ``UIImage``.
    @MainActor func snapshot(of target: some View) -> UIImage? {
        let controller = UIHostingController(rootView: target)
        let view = controller.view
        let targetSize = controller.view.intrinsicContentSize
        view?.bounds = CGRect(origin: .zero, size: targetSize)
        view?.backgroundColor = .clear

        let renderer = ImageRenderer(content: target)
        renderer.scale = UIScreen.main.scale // Adjust the scale for higher resolution
        return renderer.uiImage
    }

    @MainActor func exportImage() {
        print("Saving!")

        // 1. Grab the view as an image
        if let image = self.snapshot(of: iconView()) {
            if let imageData = image.pngData() {
                // This snippet exports the image into `Pictures` folder,
                // but you can set any directory the app has access to.
                let pictures = FileManager.default.urls(for: .picturesDirectory, in: .userDomainMask).first!
                let fileName = "icon-from-swiftUI.png"
                let fileURL = pictures.appendingPathComponent(fileName)

                do {
                    try imageData.write(to: fileURL)
                } catch {
                    print("Could not save the view into a PNG: \(error.localizedDescription)")
                }
            } else {
                print("Could not save the view into a PNG")
            }
        }
    }
}

[!note] In theory, you could save the UIImage data and present a share sheet to export it into anything you want. Saving into a directory from within a Mac Catalyst app is just the fastest way I've found, personally. Using Pictures is just the first thing that came to my mind and was in the list of autocompletions.

Make an `appiconset` with CandyIcons asset generator

There are a bunch of services and apps that take an image, and generate an app asset bundle for you, but they're not all equal. I've tried a few, and CandyIcons seems to work best. It automatically makes a mac app icon with rounded corners, and the output icon quality looks great.

[!warning] CandyIcons crashes for me when I'm trying to export icons for all platforms at once. But if I only choose iOS and Mac, it works fine.

The full code for this flow is in the Scrapes repo.

The Us vs Them Trap

nate@respawn.io — Sat, 30 Dec 2023 00:00:00 GMT

The Us vs Them Trap

I loved the chapter in Sarah Dresner's Engineering Management for the Rest of Us about the “Us vs Them” trap. I kept thinking about it, and it comes up in conversations with my engineers and peers a lot.

Here's the TLDR:

“Us vs Them” is the easiest lie people will tell themselves and everyone around them to rally a group against another group, based on arbitrary boundaries, instead of actually taking responsibility (for a situation) and having a difficult discussion about a problem.

In a workplace, it's common to refer to other teams or company leadership as "they". Sometimes that's fine. Sometimes, if you're a manager, that's toxic and stupid, and sometimes that's just a disenchanted member of a team who does not have context and clarity on a situation. Most of the time it's middle managers who fucked up.

It's middle managers' job to manage context and bring extreme clarity to contributors (why did we make certain decisions? why do we follow certain strategy?) and leadership (so that they can make good decisions, and so that the teams can actually provide input into those decisions).

Manager of managers run the business. They have the right visibility, knowing what happens in different teams, and they must pass the right context and clarity around.

As any lie, "us vs them" is intoxicating and addictive

Short-term, the first time you use this trick, "they decided that we don't get a backfill" may make the team feel that you're on their side, but leadership cut the headcount. But they will realize that it's your job to make the case for headcount, and you failed them.

Or maybe the additional headcount is indeed not needed, and then you failed to explain to them why that is the case and the decision is the right one, for the company and for them.

Either way, being honest and taking responsibility would would make the picture clear for people, and that's better than numb confusion.

Reflect on how you channel information to your team. If you realize you're saying "they did xyz" a lot, is it because you didn't realize what's going on, and that was intuitive? (bad). Or are you knowingly dodging responsibility?

You're the intersection

In a Venn diagram of your team and the leadership team, you represent your team to leadership. And you represent leadership to your team. You (hopefully) wouldn't say "they didn't ship" about your own team in a meeting with your peers — obviously, you're part of that team.

To your team, you represent the leadership crew. You're in the room with them when they make decisions. If you dodge responsibility for a decision you don't like, is it because you could not navigate your way around a discussion with other managers? Or did you agree with a decision? Or was it made without you?

Have some integrity. Get your team to follow through on what's right for the company. Quit if you realize that your leadership is toxic and you can't align with them.

If you find your leadership making decisions that make you blush with embarrassment when you explain them to your team — it can be tough to figure out if the leadership is a toxic mess, or if you lack the knowledge, context, and experience to understand why the decisions are actually the right ones. That's pretty much what mentors are for.

The Endless Pile of Notifications in Remote Work

nate@respawn.io — Fri, 08 Dec 2023 00:00:00 GMT

The Endless Pile of Notifications in Remote Work

Returning to an inbox of 400 notifications is no fun, yet you get that after a week off. On the chart of things that are difficult for [[remote-and-async-work|teams trying to work remotely]], managing communication channels and notification volume is up there at the top.

People on remote teams will get overwhelmed from time to time, inevitably. But you've been there already, you've seen it happen again and again — so why don't you prepare your teams for it, and set up your communication systems in a way that doesn't hurt their brains as much?

All you need to do is to make people agree on how quickly they expect each other to reply to what types of questions and messages, and on what channels. In practice, it's a little bit more complicated than that.

Cultures, Intents, and Expectations

Different people, different cultures. Remember the meme about what Americans and folks in different European countries mean when they say "Good" or "Interesting"? Remember how there's this stereotype about Eastern European engineers with Slavic accent being tone-deaf to the point of being rude? Right. Different cultures. We're going to make our own work culture, buckle up.

Some people assume that if they tagged you on Slack, you're bound to respond quickly, just as you would respond in a conversation if you met them iIRL. Others embrace asynchronous work and treat Slack as it was a letter in your inbox.

[!tip] You know what happens when you mix cultures without acknowledging their differences and helping them understand each other? Well, a client once told an engineer on my team "Yo, this feature is sick!". The engineer thought it's a bad thing, thought it was rude, and was pretty sad about that for a week.

It's your job as an engineering leader to listen to the people in your charge, help them agree on what communication practice works best for their group:

What's the intent expressed by a mention on Slack? Does the person need an immediate response, or no?
What's an acceptable turnaround time? In most of my teams, we mostly consider "same day" reasonable.
What channels and threads should each team member follow? If there was a chat, do you expect that people have read if they were not mentioned on that thread?
What channels follow that set of rules? What about comments on Google Docs, Loom Videos, Figma, GitHub issues?

Once you figure out the rules, it's your job to write them down, and make sure that everyone on the team actually follows them, and that the team can work well with the rest of the company.

In practice, someone on the team will be unhappy because suddenly, they might realize why they felt so awkward all the time, and that their work style is in fact not what everyone else was doing all along. Yikes. A difficult conversation for you to have. Luckily, you're a manager, and difficult conversations are what you enjoy, right?

Don't think that the only difficult conversations will be with people who don't read or reply to Slack messages. The other way happens, too. If everyone agrees that a reply on Slack is expected within a day, and someone starts texting their co-workers on their personal phones because they want an urgent Slack reply, that's unacceptable, too. If and when that happens, it might be that the offender will not be on your team. Good luck 🙃

Unsubscribe Like You're Getting Paid Every Time You Hit That Button

Once you and your team agree on how we want to talk to each other, and how we expect each other to respond, you can write down the next most important document — a guide on how to set up all the notifications on all tools that you use for work. That should be in your handbook. WDYM you don't have a handbook in a remote-first team?!

When someone on the team complains that they're overwhelmed by the unrelenting stream of notifications and messages on every channel and that it's humanely impossible to be up to date — it's your job to remind them that in a remote-first company, managing their communication is a part of their job that they signed up for.

But it's your job to make sure they know this, and to help them set up their communication subscriptions in a way that allows them to be up-to-date, and stay responsive, without exerting 10x engineer heroic all-nighter effort 3 times a week.

So, you make a guide on how to set up notifications, and you make sure everyone on the team:

Is only subscribed to the stuff that matters to them. If your team agreed that get someone's attention we mention them specifically by handle, and we don't expect them to read every thread of every document otherwise — well, that means that people can opt to only be notified when they are mentioned by name. Great!
Set up notifications for each platform. Some folks prefer keeping their email inbox empty, and check-in with each platform separately, and others prefer to dump all notifications into email, and grind through their inbox, combined. If you make a guide on how to do either of these approaches, though — that will help your engineers a lot. They're not trained to do this, so they'd appreciate the help.

Default on Notification Debt Intentionally When You Have To

Having hundreds of unread notifications that are two weeks old is not helping anyone. Give people a way out — teach them how to default on their notification debt.

When people mention someone, they generally expect that the person got the memo. But if the recipient is currently being suffocated by anxiety of having the number on the notification badge exceed the number on their checking account, it's very likely that they have not, in fact, gotten the memo.

Worry not, the only thing the recipient has to do to get out of that trap is to just intentionally, deliberately, publicly acknowledge that they're drowning in notifications, and that they will not, in fact, read them at all. Then they mark all as read. And publicly say that if anyone awaits on a response from them, or if there's anything critical for them to see — please mention them again.

I strongly believe people should have that escape hatch. But there's a caveat. Different cultures, remember? My product manager once went back online after a few days off, and asked the team to ping them on the highest priority items for them to catch up on first. Someone more senior on another team looked at that and asked me why that product manager thinks their time is more valuable than ours, and why can't they catch up on their own.

This ritual needs to be alright with everyone. It's not because people are lazy, it's because spending days and days reading stale notifications is not the best use of time. Nobody should think less of others just because they default on notifications in extreme situations.

Just like unlimited PTO, of course, it's a trap. If someone starts every other week with "Happy Monday! I won't read my notifications, ping me if you need me" — you two are overdue for a chat.

When Mentioning People, Leave Meaningful Context

This one is best in a form of an example.

You have a senior software engineer, Julia, who is just fantastic — she's been with the company for a long time, and built quite a few things, in different areas of your product. She recently led a feature-team, and the feature was merged and shipped under a feature flag a month ago.

Your account managers released it to customers in waves, and now your product manager Patrick has a request for an improvement that they have left as a comment on the Google Doc with the original feature spec.

Patrick made a first comment with a description of an edge case that was, on it's own, well-written. But they didn't mention anyone, and for that sin, they did not get a reply in the next two days.

Patrick: Hey, so in a situation when this widget does not have enough data for the second line on the chart, can we show a little notice with a button to connect additional data stores?

Patrick is smart, they realized their mistake. So they reply to their own comment:

Patrick: Hey @julia, can you take a look?

So, Julia receives an email from Google Docs that has just this — hey Julia, can you take a look? Sure, it has a link, but just scanning this — Julia has no clue what the hell she's stepping into, clicking on that link. She also does not know what Patrick expects her to do — does he expect her to work on the feature? Did he already talk to her engineering manager about it? etc.

[!tip] When mentioning people, add concise, meaningful context. One sentence should tell people what they're looking at, what action is expected, and where to learn more.

It Patrick asked you how they could improve their comment, you should tell them to write something like:

Patrick: Hey @julia, in the dashboard widget you shipped last month, there's this edge case. I'm looking for your feedback before I file a ticket. Not urgent, I don't expect you to build the thing.

I've posted a few notes on remote work:

[[remote-team-health-check|Remote team health check]] on how to quickly assess strong and weak sides of a team, and figure out what to focus on as a leader.
[[remote-and-async-work]] on how to strengthen an asynchronous remote-first work environment.

There's no right or wrong way to work. Just like technologies and frameworks, the work communication framework you use is a tool. You choose a tool based on the job at hand, and on what you and your team know well.

If the team likes hybrid work, or likes to huddle at a white board with pizza and bears, and it works well for them — you probably should not try and change the whole team.

The Trade-Offs of Designing in Html and Rails

nate@respawn.io — Thu, 30 Nov 2023 00:00:00 GMT

The Trade-Offs of Designing in HTML and Rails

Folks at 37Signals have strong opinions on how to design and build products for the Web. Between ShapeUp, design philosophy, and Rails approaches to frontend, monolith vs services, and infrastructure, there are a number of conventions.

I don't like the personalities behind them, but the approaches are generally very sane for the audience they're articulated for.

The Basecamp way of ShapeUp, and the design philosophy, though, don't generalize very well, in my experience.I'm yet to see an organization successfully and happily using ShapeUp in a team bigger than 50 people. Get it? Rails (approach) doesn't scale? Hehe.

Designers Who Can Write Code Absolutely Rock

People who span across several areas of the work, generally, have a much stronger understanding of the overall goals, values, and motivations of the product. And as such, they're able to bring extreme clarity to the rest of the team. They're moving quickly. They have their own opinions about the product you're building. Designer + Engineer combo is not an exception from that rule.

In Zipline, I've been privileged to support not one, but three absolutely amazing designers-turned-frontend-engineers. With them, and with ShapeUp, early on, we've been able to iterate on our products very quickly, and with a very respectable level of clarity for everyone involved.

When I worked on my own company, Amplifr, and later in Evil Martians, I had the pleasure of working with Andrew Sitnik, who you might know by his work on Autoprefixer and PostCSS. He basically designed all of Amplifr in the early years, from scratch, and also built half of the UI. He thought through the whole product experience.

In Amplifr, we were not just building a standard-issue Rails application. We were not confined to the Rails "DHH-approved" stack. We've built out optimistic UI with CRDT over Logux backed by a Rails backend.

I do have to admit, teams that build with Rails are capable of building a lot, and doing so quickly. So while it might be very difficult to scale and grow such a team beyond certain threshold (more on this below), you can get very, very far with a small team.

Designers Who Can Code Are Also Rather Rare

When we've been recently looking to hire product design folks at Zipline, it became pretty clear that even in the 2022-2023 market, folks who can design and implement their designs in HTML are rather rare. Folks who can do that, and are also experienced in the Rails stack, are even more exceedingly rare.

The problem here is that once you set up a team where your designers are expected to write Rails views, and contribute or prototype controllers for features they're envisioning, that team will have a very hard time onboarding designers with any other experience profiles.

"Rails stack" (Rails views, Hotwire, Stimulus, designers write said views) is great early on, but the more you align with it, the harder it might be to scale the team:

Rails frontend is not an "industry standard" for designers. They don't have the tooling that they're used to.
If your team thinks and designs in code, they won't really like jumping into Figma and navigating your product designs in Figma once the team starts using it.
Rails apps usually have a semblance of an implicit design system in their views and partials. Once you try to design in Figma, there will be a very well-meaning designer who starts tweaking the very primitives of your controls, and the design system brain split will be painful.

Designing in Code Limits Your Creativity

[!tip] Sticking with just one mental model limits the points of view you consider, limits your creativity in how you solve a problem.

The problem with designing and prototyping straight in HTML or Rails views is that it limits the level of polish and creativity that your team can apply to solving a problem.

Amplifr's team won't be able to build optimistic UIs with Rails primitives consistently, not at that time (Turbolink's idea of fragment reloading was shoving js code in .slim partials, good luck with that).

Think about the most beautiful and amazingly functional products you know of. They're likely not designed in code. Stripe's homepage and product documentation are likely not designed in HTML, despite Stripe using Rails heavily.

Admittedly, most Rails apps don't need to push design to the limit of what's possible with modern HTML and CSS. Depending on what audience is using your product, perhaps Rails frontend and Rails approach to design are totally fine! Most SaaS products out there just take content in, process it, perhaps sync in some more data from other systems, and present text content in different views and drilldowns. It's fine to use primitives that people already know and love, take an off the shelf design system and go for it. Twitter Bootstrap, Tailwind, Shopify Polaris, GitHub Primer, Stripe Elements.

But sometimes, you need to drop the constraints of the technology that you have today, and think about what a great solution to the problem looks like, and then think backwards from that — think about what technology you need to make that solution a reality. If you only have designers-who-html on the team, they likely won't be as great at that type of work.

The Cost of Lifting the Product Design Process Away From HTML

Designing a good product starts with the problem, and describes the why, what, and how of the solution. It's not just the visuals. Starting with what and why means thinking about the product and the people using it, and what success looks like to them, and articulating that thinking in a format that others can read and debate.

Designing and prototyping in HTML gives your team that shared language of the prototype. Not designing in HTML means that the design and product team need to find that language, and build that system and the process of how you talk about your product, design, and implementation. That's usually expensive. At the very least, that would mean using additional tools (Figma, Miro, you name it), having more channels for conversations (not just issues and PRs, now you have threads of comments on Figma, too), and the process will take more time, more discussion, more deliberation.

And the biggest cost of all is that you as a leader have to bring clarity to everyone, put them on the same page, make sure they have the same goals in mind for your features, your product, and your customers. And that's usually extremely difficult to achieve.

That's why many folks in the Rails ecosystem revert to the fat marker sketch, design-in-HTML approach. They know it works. They don't trust the other process that seems risky and wasteful. And so they stick with what they know. But quite often, it's the right approach for them.

For some products, you need to move quickly and be able to take the prototype, clean it up a little bit, handle the edge cases, and ship it as a new feature, all in just a few hours. For others, you need that space, you need more people, more opinions, more angles, and more time before you commit and build.

Switching to Asynchronous Remote Work: Challenges and Best Practices

nate@respawn.io — Sun, 05 Nov 2023 00:00:00 GMT

Switching to Asynchronous Remote Work: Challenges and Best Practices

Someone recently mentioned to me that they've gone back to the office for two days each week, and it gave them a huge productivity boost — "we get so much done in those two days — stuff that we can't otherwise get done in a month".

Remote work doesn't suck. Attempts to shove in-office meeting HiPPO culture into a remote medium sucks.

People seem to confuse asynchronous trust-driven remote work and office culture inspired remote work. Remote makes many things so much easier, but some things become very challenging. Meeting time becomes an expensive luxury.

So if to get anything done you need a synchronous meeting with several people to discuss a thing, and then another meeting to make a decision, and then yet another meeting to tell other teams about that decision — you're royally screwed. Everyone on your team will be burned out and exhausted after several months of that clown fiesta.

That's why teams who figured it out stress that communicating in writing with extreme clarity is so important. You do that thing called actually reading and writing. A document about why you need a decision and what you're leaning to, inviting others to collaborate. A Slack message (on a public channel, please). An email, if you feel like a fossil today. Bonus points for including a diagram or a Loom video.

That mode of work requires everyone to trust each other and treat each other like adults. It requires people to be engaged, have the same goal, and be excellent in their communication. Hence, it is difficult to switch to — and I get why larger companies who had to go remote 3 years ago are now going hybrid. All their previous lives they've trained their teams and leaders to work in a certain way, rally their teams around the whiteboard.

Embracing Asynchronous Work

When leaders (and all teammates, really) start working remotely, a few things are usually new to them. They would try and do things just like they used to in the office, replacing a meeting room with a Zoom window. But it doesn't work well. That approach doesn't play to the strengths of the remote environment.

If you like snowboarding and surfing, you wouldn't try and surf wearing your full winter snowboard gear, right? The same applies to async remote work.

Here's the list of things that I highlight to people that I mentor, and how I explain the pros, cons, and reasoning behind each of them.

Communicating With Radical Transparency

Whether you're making a decision, or just asking where in your codebase a certain feature is, please, try to have all work project-related conversations in the open channels with clear naming, instead of direct messages.

Here's why:

You're not the only person with that question or decision, I promise. Others will try to look for that information soon. They'll try and search for it, and they will have to ask the same question in DMs it wasn't shared publicly in the first place.
If you have multiple DM conversations about the same thing, you can easily get into a situation where people will have dangerously different and conflicting ideas of what you actually decided to do.
When people have work conversations in the open channels, it feels like everyone is engaged.
It's faster. Async work treats Slack like email. If you DM an engineer who is in deep flow, you won't get an answer quickly. But someone on the channel might know.

Here's how to coach people to talk in the open:

By example. Do your part — instead of DMs, work in the open. Loop people into conversations — tag and mention people who you know will need this information.
When someone asks you a question — it's absolutely necessary to post your answer into the open channel, and comment that "Hey folks, @xyz asked about this, and here's what I think. Am I missing anything? Does it look correct to you?". In DMs, politely explain why you prefer to answer this way, and ask that the person posts their questions in the channel and mentions you, instead of a DM next time.

You will have to do this many times with many people on your team. Some people get comformtable posting in the open quickly, but others might take several nudges to change their ways.

Making and Documenting Decisions

In the office, you can just sit down with the team that you need and make the decision in a meeting quickly. Working remotely, you can still run a meeting (and it has its own pros and cons), or you can drive to a decision asynchronously.

Working asynchronously requires you to communicate in writing instead of video and voice meeting, and that has tremendous advantages!

You can easily review and untangle the logic of why a certain decision was made if it's in a document with threaded comments.
Everyone on the team will learn to communicate clearly, and structure their thoughts, if they have to write them down.
You have time for a thorough review and debate. Not everyone is comfortable raising their hand and speaking up in a meeting. Some folks need calm time to review, think, and write their questions and ideas down. Asynchronous discussion makes it easier for them to open up, and contribute.
You get better documentation. Some people like reviewing information by reading text. Others prefer videos or diagrams. Maybe there are folks who actually love voice messages, but I have yet to find them. And so, people learn to record video summaries (thanks, Loom!), use diagrams (GitHub Flavored Markdown renders Mermaid btw), or work in Miro.

But, async decisions may feel slow. Some decisions are straightforward, and you expect that most or all people on the team will agree with them. Some decisions so small that an RFC-style document is an overkill. Some decisions feel so urgent that it feels like there's no time to have a discussion.

Remote / async work does not require that you have lengthy discussions about every decision and lose time on them. It's the other way around! Async work means that you choose the right medium to communicate your goals and intentions.

You start an RFC-style discussion where you suggest a plan, and immediately start working on your approach.

Sometimes, admittedly, that means you will throw away your prototype if the team is convinced that you should take another path ;-)

How to help your team get better at async, documented decision-making (ugh, that's a separate post worth of stuff):

By example. Write notes where you outline the problem you need to solve, the ideal successful state, a couple of possible approaches, and the approach that you plan to take.
- Set the timeline: communicate how much time folks have to contribute.
- Set the expectation of who should contribute. If you expect certain people to comment, approve, or add suggestions — ask them specifically.
- Set the expectation about following through on the decision. Who is going to drive the discussion forward? Are you delegating it to someone, or will you return and wrap it up?
Help others write their proposals, notes, and documents. Especially true if you support software engineers. Help them learn how to communicate their work better, and they will push your whole organization forward.
Help others make their voices heard. Remote is great at surfacing who is very engaged, and who seems to be shy and just get their own work done. Check-in on them, and make sure you support people who have a lot to contribute, but who shy away from it.

Set a clear expectation that participating in discussions is a big and important part of their work, and it's okay to spend time on it. Maybe they're drowning in work on their projects (your job to help them, btw), or perhaps they didn't get the memo (your job to help them, btw), or they don't have anything to contribute (unlikely, but your job to help them level up, or level out, btw).
Normalize prototyping and discarding work if the decision changed. When a decision is urgent, you can ask the team to start working in a direction before it was confirmed. Normalize that style of work — that will help you remove the perceived slowness of remote. Show the team that you know there's a trade-off, and that you deliberately ask them to start working, knowing we might end up discarding some of their early work if we choose to go in a different approach.

You Should Really Say "No" More Often

nate@respawn.io — Sat, 05 Aug 2023 00:00:00 GMT

You Should Really Say "No" More Often

Saying "no" unlocks much more for your team and your company than saying "yes" to every project and ask. Here's how that usually works.

You're leading a team, and you're very good at building bridges and working with other teams. Sometimes you help your team get a feature over the finish line and write a little bit of code. Sometimes you help an account manager, and fix an edge case bug for that a customer reported.

These little asks add up, and together they eat up more and more of your time. A couple of hours every week at first, but then you find yourself in five customer meetings in a single week, and you've promised to ship a few little improvements to three different people in CS. What happened?

On a 1:1 with your peer engineering manager, you talk about how your engineers are not quite engaged with the company beyond just writing and shipping code, and how you ought to work on that. Well, congratulations, because what you thought of as "leading by example" is actually doing the opposite.

The part that everyone knows about

Let's get the basics out of the way. When you say "yes" to one thing, you're saying "no" to everything else that you could've done in that time.

If you agree to many small asks from others, you're implicitly not spending the time thinking strategically about the core of your own work and growth. Thinking strategically takes time. Doing lots of one-off tasks also takes time. You'll get many asks and nudges as your work becomes more visible in the company, that's a given. You will not get many nudges to think strategically from your boss in a startup — they're likely busy doing one-off asks from others, and didn't make time to think about your growth.

So, saying "no" to small asks from others makes it possible for you to make time and think about the work that is important to you strategically.

Saying "no" helps your team grow and learn

When an account manager asks you to implement an edge case in a feature for a specific customer, what if instead of saying "sure, I can do that by Thursday" you started a thread with one of your engineers, and asked them to work on it?

Weaving one-off asks into your team work cycles solves several problems at once:

You can coach an engineer in thinking about the time trade-off, and tactically solving a problem for a customer, and building a stronger relationship with an account manager. That helps engineers understand why solving a problem for a customer or a prospect is important, or why we should say nope to that ask, and hence understand the company values and strategy better.
You make this work visible to others — including other engineers and your product manager. After a few sprints or cycles, you should be able to reserve some resource for the work that will come up with less resistance, and get a bit more slack for folks on your team.

At first, delegating work to your team that way will take more time than it would take to do it yourself. But the time you invest in coaching your team compounds. After the first few delegated tasks, you won't need to coach and explain the task to your engs as much, you will have good visibility into the work, and you'll have your time back.

My good mentor always told me: anyone can build a feature on their own. Try coding it up without using your hands.

Saying "no" helps others do more with less

Some habits take years to build, but the habit of asking for someone's help if you know they will deliver, forms dangerously quickly. If your work is visible, you show up, and you care a tiny bit too much about helping others, then you'll have a line of folks asking for your help often.

In some situations, people will relay an ask to you without even stopping to think if they can solve it themselves, or if it needs to be done at all:

Hey, can you quickly pull in a report from our BI tool? It looks scary, and I'm not sure how to use that no-code report builder myself — sure, you can do it in 30 minutes. It would take 2 hours to teach the person to build the report on their own. But you can record that session, and ask others to watch it, and then they can build their typical reports on their own. There — you just took your time back, and taught the whole team how to solve a typical ask with a quicker turnaround.
Hey, can you build a custom report that has data from both of these reports, but in the BI tool, so I can export a spreadsheet? — sure, but what if you just take the two report spreadsheets, copy all the sheets from one to the other, and make a new summary sheet that glues them together on your own? Time for some excel-fu, haha! Of course, it's easier to ask yxsou than to do some work on their own. But it's perfectly fine to say no.

Saying "no" shows your team that it's okay and healthy to do so

Your team is looking up to you, seeks every subtle signal on what you expect from them. They take both strong signal from what you say and write, but they notice what you do even more.

If you want folks on your team to take care of themselves and take time off regularly, but you never take time off yourself — you're showing them a wrong example.
If you want folks on your team to not burn out at work, but you regularly work through the night and then tell everyone how you didn't have enough sleep and how you're tired and exhausted — well, that doesn't help. Even if you're doing that to shield them from extra work. The power balance on the team likely makes them feel that hardcore work is expected.
If you want your teams to stay focused on their main goal for the month or the quarter, but they see you constantly being torn between twenty different little things — that will send a message that aside from their main goal, they're expected to say yes to everything, and saying no to extra work or an ask is not okay.

Learning to say no and to make time to stop and think strategically is one of the most important skills for a people leader.

Especially if you're a manager of managers in your current role — do make sure that your managers are not burning themselves out with endless one-off asks from others. In a way, this makes your job easier — you can coach your managers to take care of themselves and their time, and to think strategically. Then you set a goal for them to coach their team in the same way.

Using Contentlayer with Next.js

nate@respawn.io — Mon, 10 Jul 2023 00:00:00 GMT

Using Contentlayer with Next.js

I've just added a new section to this blog — Today I Learned notes. With that, I'm writing down a few other things I've changed around, and how it works together.

Contentlayer in a statically generated site

First off, Contentlayer. It simplified things quite a lot. If I had half a brain left back when I started the blog, and used 11ty instead of the monstrocity that Next.js is, Contentlayer would be an overkill. But with Next.js, you don't get the automatic pipeline that grabs all of your markdown files and renders them — you build that pipeline yourself.

And that generation pipeline generally consists of a few stages:

Read the source files, populate and compute their fields based on frontmatter or whatever custom logic you want, and define your types. For me, that was a lib/posts.ts that has just a handful of functions and made sure that Post.created is actually a date.
Configure and setup a way to process markdown. That would likely involve MDX or next-mdx-remote or something similar. Not too complex, but that's just boilerplate code. Would be cool if you didn't have to write boilerplate, huh?
Rendering your content within the site URL structure — Next.js makes that relatively straightforward.

Coming from the world of OG backend web frameworks (Wait, is Rails and Symphony OG?), Contentlayer looks similar to what you'd call an ORM, except it's not exactly a relational mapper. You could say it's an Object Markdown Mapper questionmark.

Anyway, Contentlayer allows you to specify what fields (and types) your markdown sources have, and then it will generate the types and objects for you, including a nice allPosts() or allPages() or allWhateverYourTypeIs() that fetches them. The only thing left for you to write is a function that grabs your processed content and sorts it. Here it is in this blog's repository.

To get all that, you specify your source data type and fields in a contentlayer.config.ts file:

// contentlayer.config.ts

// Use defineDocumentType to describe each source file type.
// Each type will have `content` field automatically, but you can add
// `fields` that are based on frontmatter keys, and
// `computedFields` that are computed when the object is instanciated.
const Post = defineDocumentType(() => ({
  name: "Post",
  filePathPattern: `posts/*.md`,
  contentType: "mdx",
  fields: {
    title: {
      type: "string",
      description: "The title of the post",
      required: true,
    }
  },
  computedFields: {
    slug: {
      type: "string",
      resolve: (doc) => `${doc._raw.sourceFileName.replace(/\.md$/, "")}`,
    },
  }
  // ...
}

// call makeSource to tell Contentlayer to actually run and generate your data
// into objects.
// This will generate a ./.contentlayer/generated directory with a bunch of typescript
// files that describe your data.
export default makeSource({
  disableImportAliasWarning: true,
  // where your content is located. Each content type's filePathPattern is relative to this.
  contentDirPath: "content/",
  // what data types to generate? In this example, there are just posts, but you can add more.
  documentTypes: [Post],

  // mdx settings to use — that's where you put all your remark and rehype plugins,
  // without the rest of the boilerplate!
  mdx: {
    remarkPlugins: [
      remarkGfm,
      [remarkFigureCaption, {captionClassName: "text-center italic"}],
      [wikilinks, {pageResolver, hrefTemplate, aliasDivider: "|"}]
    ],
    rehypePlugins: [
      [rehypePrettyCode, prettyCodeOptions],
      rehypeMermaid
    ]
  }
});

It also works well with MDX, and that comes in two pieces. First, you tell Contentlayer that you're actually about to render some MDX, and specify what plugins you want to use in remark and rehype:

export default makeSource({
  disableImportAliasWarning: true,
  contentDirPath: "content/",
  documentTypes: [Post, Page, Daily],

  mdx: {
    remarkPlugins: [
      remarkGfm,
      [remarkFigureCaption, { captionClassName: "text-center italic" }],
      [wikilinks, { pageResolver, hrefTemplate, aliasDivider: "|" }],
    ],
    rehypePlugins: [[rehypePrettyCode, prettyCodeOptions], rehypeMermaid],
  },
});

And then you render your content with a component that Contentlayer makes for you in getMDXComponent:

// import the function that returns an MDXComponent based on your data type's mdx content
import { getMDXComponent } from "next-contentlayer/hooks";

export default async function Post( { params }: Params ) {
  const post = allPosts.find((post) => post.slug === params.slug);

  // Get an MDXComponent that will render the post's content.
  const MDXContent = getMDXComponent(post.body.code);
  return (
    <>
      /* Pass additional mdx component specifications as needed */
      <MDXContent components={mdxComponents} />
    </>
  )

Adding multiple source types to your Contentlayer configuration

So what if you want multiple types of posts, with different fields? Well, you defineDocumentType several times, but then your contentlayer.config.ts starts to cause pain comparable to package.json. So as any sane person who dealt with an ORM before, you split it into the config itself, and the data definition files that you can tuck away in lib, like this:

// lib/page.contentlayer.ts
import { defineDocumentType } from "contentlayer/source-files";
// Page is a simple type to hold the content
// of a page. Currently used in `/about`.
export const Page = defineDocumentType(() => ({
  name: "Page",
  filePathPattern: `pages/*.md`,
  contentType: "mdx",
}));

// contentlayer.config.ts
import { Post } from "./lib/post.contentlayer";
import { Page } from "./lib/page.contentlayer";
import { Daily } from "./lib/daily.contentlayer";

Here's the commit with that split for respawn.io.

And here's the full contentlayer.config.ts — that now defines wikilinks, some other formatting, and uses rehypePrettyCode for code blocks. At the time of this writing, 38 lines of code to bootstrap all of that.

I think I've played with Next.js for a little bit too long, so I'm no longer sure if that's actually neat, or if that's way too much. But after tinkering with next-mdx-remote and friends, I'd say 38 lines for the whole mdx conversion configuration is pretty cool.

Remote Team Health Check

nate@respawn.io — Sun, 25 Jun 2023 00:00:00 GMT

Remote Team Health Check

I've been away from my team for almost a month and a half. No checking-in on Slack, no reading weekly posts on Basecamp. I didn't know what was happening, and of course, I was anxious about it.

We're a fully remote company, and every time I get back from time off, I scan for how the team is feeling. You can usually scan your team's communication channels in just a few minutes to get a picture of whether the team is happy, motivated, and productive, or stressed, burned out, and confused.

Here's the list of things I look for to get that picture. Your list may vary: each team has their own culture, so their "happy place" will be different. But the principle stays the same — quick scan to see where your attention is needed most.

Are people working in the open?

Do you see folks talking about their day-to-day work in the open Slack channels (or Discord, or whatever else you use)? Asking for a review, syncing up between platform and product, frontend and backend engineers, quick asks about different pieces of your system, or product or design questions — do you see them in the open?

Working in the open channels is essential (to me) in remote environments: it lets others chime in, understand how things work, see the progress, or search for that topic in the future, or support the work if the team needs help, or if someone has a few days off, and someone else is picking up their work.

If you don't see open chatter — it's either because no one is talking about day-to-day work at all (unlikely, but that's a different problem), or because everyone is siloed in their DMs.

If you've seen the chatter before you left, but it died out without you — think about why nobody else sees talking in the open as beneficial, or why are they afraid to or shy to post in the open. Do you see judgement, "well, actually", or other form of lack of support when people did talk in the open previously?

Are people asking for help?

Do you see people asking for help and advice? Sharing their in-progress work? Admitting they're struggling with a task, or admitting mistakes?

Some teams prefer a more open and direct culture than others. But in all teams where people respect and care for each other, they would support their teammates when they need help. But to share a work-in-progress, or admit a mistake, people on the team need a pretty high level of trust with each other, and with their organization leadership. Nobody would share their mistakes if they thought that doing so would affect their next performance review in a bad way.

So if you don't see any of the vulnerability and camaraderie in the team, it could be that no one needs help, or makes mistakes, or gets blocked ever (lol no, they do). However, it's much more likely that people are afraid to talk about their mistakes in the open because they don't trust that other people on the team, or you, will not use that against them.

In my experience, that kind of trust starts with leadership. Believe it or not, nobody expects you to always be right. And when you tell your team that you need help, or ask for help for help, or tell them that you made a mistake — it empowers your team to do the same. Of course, that only works if you don't punish people for making honest mistakes.

Are people debating ideas?

Do you see any new RFCs, or just discussions about how to build a feature, or what architecture would work best? Do you see respectful disagreements and debates? Strong arguments and spikes to support ideas?

RFCs, Disagreements, and debates are all critical to building a resilient, open, serene organization that sources ideas from all the talented people on the team. But it's pretty hard to get right.

Discussions take time to think and prepare through a problem at hand. Articulating engineering opinion is both a communication task (writing and presenting), and an engineering task (research, proof of concept or a spike). It's your job as a leader to balance your team's backlog in a way that gives them enough slack-time.

Disagreeing in public and taking time for research work can feel scary for the people on your team. If that work is not recognized, or if the discussions are routinely shut down and discarded because of a pressing deadline — no one will risk taking the time to articulate and post their opinion anymore. Which is pretty bad for your team's culture, and for the company as a whole, as it limits where you get new ideas. Why hire the smartest people you could find, and then shut them down?

So, if you don't see any back-and-forth on ideas on how to implement features, and close to zero feedback on pull requests overall — you should absolutely dive deeper.

Do people have a shared goal, a path forward, and a clear indication of their progress?

To stay engaged (with the company) and energized, people really need a plan that makes sense to them, an explanation of why that plan is important, a picture of what everyone else in the company is doing, and an indication of how they're doing as a team and as a company.

In the first few 1:1 conversations, ask about what goal do they think their team is working towards, and what are the next steps for them. Is there a consistent picture of the team's goals? Do people know what they're working towards, how it contributes to the company, and where they are on the path to that goal?

For people to stay engaged with the company strategy, someone has to connect them to it, and consistently relay any changes in strategy, and broadcast the current state, and the path forward.

It's your job as a leader to communicate the strategic goals, and the tactical goals to your team. If you put the right systems and communication channels in place, then your team should at the very least be informed and well-connected internally. However, your time away puts those communications systems to a serious stress test — you were not there to course correct if they didn't work.

The same goes for understanding where the company, the organization, and the team is now in their path towards the goal.

Are people cheerful?

Do you see folks recognize each other's work, and support each other?

If your team has daily written check-ins, do you see people reacting to each other's check-ins? Congratulating each other on work well done? Do people check-in at all? If you see any outliers that dropped the habit, can you figure out why?
If you have regular sync calls to check in — do people gladly share their work in progress with each other, and ask questions, or do you have to call out each team member one by one and inquire about their progress?

Engaged teams work together. The recognition and energy helps push the project forward. If you have to pull the progress out of people on your team, and the morale seems down — it's likely a combination of factors described above. Lack of clarity, lack of autonomy, lack of recognition, lack of support, or an otherwise toxic environment.

If your team culture does decay, it usually starts slow, but then snowballs. Lost trust is very difficult to rebuild, so hopefully you catch the first signs of problems in just one area before it's too late, and immediately make time and a plan to improve on it.

Automating Swift Docc with Github Actions

nate@respawn.io — Fri, 16 Jun 2023 00:00:00 GMT

Automating Swift DocC with GitHub Actions

Some languages have nice documentation tooling: Yardoc for Ruby, Pydoc for Python, Godoc for Go. Swift has DocC, and it can export docs as a static website, too.

This is part 2 of [[swift-docc-publishing-workflow|Generating Swift DocC archives guide]]. In this post, you'll take the Vue.js app that Swift DocC builds, host it on GitHub Pages, and write a GitHub Action to automatically rebuild and update your docs when the source code changes.

Setting Up a GitHub Pages Site for Your Documentation

On GitHub, go to your repository Settings → Pages, and set it to deploy from a branch. Select gh-pages branch, and /docs folder. If the gh-pages is not on the list of available branches — create it, and push it up.

$ git switch -c gh-pages
$ git push origin gh-pages

Note: This guide assumes that you'll be hosting your docs on github.io, and your GitHub Pages site URL will look like ${username}.github.io/${repository}.

If you'd like to deploy DocC site to a custom domain — that'll work, too, but you will need to not set --hosting-base-path.

Manually Deploying the Documentation to GitHub Pages

For this example, I've forked out apple/swift-package-manager. The code examples below work on that repository.

# Assuming you're in the Swift project directory (in this case, swift-package-manager itself), 
# and that your `Package.swift` already has a dependency on swift-docc-plugin.
# Runnig this will get output a `./docs` directory containing the site that we need.
$ swift package --allow-writing-to-directory ./docs \
	generate-documentation --target PackageDescription \
    --output-path ./docs \
    --disable-indexing \
    --transform-for-static-hosting \
    --hosting-base-path swift-package-manager

# Make a new gh-pages branch
$ git switch -c gh-pages
$ git add ./docs
$ git commit -m "Swift DocC site in ./docs"
$ git push origin gh-pages

It takes a few minutes to process, but when it's done, you'll get a webpage like this one.

Note: Swift DocC site is only available in a subdirectory for your particular target: /documentation/{targetName}. It would be great to have a root web page, but I don't yet know how to craft that.

So far, you've generated Swift DocC documentation, exported it as a static website, and shipped it to GitHub pages. Now let's automate it, so every time you push an update to your library, you get the updated documentation website for free.

Using a GitHub Action to Deploy Documentation

Here's a workflow that will build DocC website, and push it to GitHub pages automatically:

name: Build Swift DocC and publish on GitHub Pages

on:
  push:
    # If you wanted to only trigger this flow on certain branches,
    # specify them here in 
    # branches: 
    # alternatively, you can trigger docs only on new tags pushed:
    # tags:
    #   - '*'

# `concurrency` specifices how this action is run. 
# Setting concurrency group makes it so that only one build process runs at a time.
concurrency:
  group: "pages"
  cancel-in-progress: false

env:
  # Build target specifies which target in your Swift Package to build documentation for.
  # To build all targets, remove this env variable, 
  # and remove --target arg in the building step below.
  BUILD_TARGET: PackageDescription

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout
      uses: actions/checkout@v3
      with:
        fetch-depth: 0

    - name: Set up Swift environment
      uses: fwal/setup-swift@v1
      with:
        swift-version: '5.8'

    # Build the DocC website using swiftPM.
    - name: Build docs with SwiftPM
      run: |
        swift package --allow-writing-to-directory ./docs \
        generate-documentation --target ${BUILD_TARGET} \
        --output-path ./docs \
        --disable-indexing \
        --transform-for-static-hosting \
        --hosting-base-path swift-package-manager

    - name: Commit and push generated documentation
      run: |
        git config --local user.email "github-actions[bot]@users.noreply.github.com"
        git config --local user.name "github-actions[bot]"
        git switch gh-pages
        git add ./docs
        git commit -a -m "Generated Swift DocC"
        git push origin gh-pages

Building Swift Docc as A Static Website

nate@respawn.io — Fri, 09 Jun 2023 00:00:00 GMT

Building Swift DocC as a Static Website

Swift DocC is great. I love how it encourages you to write documentation while you're coding, and how it enables you to link up symbols so that the overall system is easier to grasp, both in Xcode suggestions, and in the documentation viewer app.

And the tutorials DocC makes are pretty good, too! I've been playing around with Swift, and considered building out a few ideas as DocC tutorials. No idea if that's going to work out. But on my journey, I've figured out how to build DocC doc archives, how to host them, and how to automate the whole flow.

Part one (this post) is how to build and export your documentation. Part two will cover hosting it on GitHub pages, and automating the publishing flow with GitHub actions.

Generating DocC documentation

Apple mostly talks about how to generate DocC archives with Xcode (Product → Build Documentation Archive). Xcode is great for authoring and building documentation, but you can also use SwiftPM and swift-docc-plugin to generate documentation without Xcode (yep, that should work on Linux hosts, too).

Step one is to add swift-docc-plugin to the package definition in Package.swift.

let package = Package(
	name: "SwiftPM",
	// Omitting products here..
    products: []
)

// Assuming you have a package object,
// you can just append a dependency like that:
package.dependencies.append(
    .package(
        url: "https://github.com/apple/swift-docc-plugin",
        from: "1.0.0"
    )
)

In this specific example, I'll work on SwiftPM's own documentation. If you'd like to, you can clone apple/swift-package-manager and follow along.

Step two: once you have the plugin setup, you can generate the documentation archive in CLI like this:

# This will output DocC archive in .build/plugins/Swift-DocC/outputs
$ swift package --disable-sandbox generate-documentation \
	--target PackageDescription

Step three: you can also export your documentation to be served as a static website, and there are multiple ways to do it:

The minimal approach is that you can use .htaccess rules to serve the archive as is.
You can export the documentation bundle as a statically generated Vue web app. Instead of a .docarchive, you'll get a directory containing the web app:

swift package --allow-writing-to-directory ./docs \
    generate-documentation --target PackageDescription \
    --output-path ./docs \
    --transform-for-static-hosting \
    --hosting-base-path PackageDescription

To preview the resulting website on your local machine, run this:

swift package --disable-sandbox preview-documentation \
	--target PackageDescription

You get filtering and search out of the box. Since the resulting directory is a static website, you can host it pretty much anywhere you want.

In the next part, I'll show you how to set up GitHub Pages to host the DocC archive, and how to automate building it anytime you push a new version of your code.

Setting Up a New Mac with Dotfiles, Brew Bundle, and Mackup

nate@respawn.io — Wed, 14 Dec 2022 00:00:00 GMT

Setting Up a New Mac With Dotfiles, Brew Bundle, and Mackup

I was rather stubborn at having just one laptop for work and personal use, but finally decided it's time to separate the two activities out. So it was time to setup a new machine!

Everyone has their own little script to set things up. I just had a dotfiles repo that I mostly used to to set things up on Linux boxes. Here's how I cleaned it up:

dotfiles with dotbot with settings for common unix software, the usual. This way, the first layer of the backup is applicable on any POSIX platform.
Brewfile for brew bundle install downloads all the things, including apps from casks and Mac App Store. Here's my current Brewfile. UPD: turns out, it bundles vscode extensions in it, too — that's not necessarily the best way to manage your VSCode extensions.
mackup restore grabs Mackup dump that has Mac-specific apps and settings.

Backing Up the Old Machine

To setup a new machine with just the software and configuration that you need, you first need to back it up from the old machine. Here's the minimal path to get it to work with the dotfiles like mine:

Backing Up Your Dotfiles

First, you need to install dotbot and move your existing configuration files into a dotfiles directory and push it up to a git or Mercurial repository. Here's the installation instructions on GitHub.

If you already have a directory with dotfiles — great! You can restore them manually, sure, or you can still use dotbot install script to simplify it for you, or run arbitrary commands after copying the dotfiles over. The internal structure of your existing dotfiles does not matter, you can configure it for dotbot in install.conf.yaml.

# First off, you need to make a directory to collect all the important dotfiles.
# This example assumes a new directory, but you can just cd in yours if you have one already.
# This example is based on the one in dotbot GitHub, but tweaked for my personal directory structure.
mkdir -p ~/src/dotfiles
cd ~/src/dotfiles
git init # initialize repository if needed
git submodule add https://github.com/anishathalye/dotbot
git config -f .gitmodules submodule.dotbot.ignore dirty # ignore dirty commits in the submodule
cp dotbot/tools/git-submodule/install .
touch install.conf.yaml

# install.conf.yaml
# This example is based on my install.conf.yaml at the time of the writing:
# https://github.com/natikgadzhi/dotfiles/blob/main/install.conf.yaml
#
# Here's the dotbot config guide: https://github.com/anishathalye/dotbot#configuration

# By default, create, relink, and rewrite each config file defined in this config.
- defaults:
    link:
      create: true
      relink: true
      force: true

# clean will prune any dead symlinks to any of the listed file paths below in the directory.
- clean: ["~"]

# links specify which configuration files from the dotfiles repository to
# link on a target system, and where they should be located on
# the target system, and in the repo.
- link:
    ~/.tmux.conf:
      path: .tmux.conf
    ~/.gitconfig:
      path: .gitconfig
    # Take all of the files and directories in .config dir of this repo,
    # and link them to the target system
    # at ~/.config.
    ~/.config/:
      glob: true
      path: .config/*
    ~/.gnupg/gpg-agent.conf:
      path: gpg-agent.conf
    ~/.ansible.cfg:
      path: .ansible.cfg
    # This is the neat part: dotbot configuration manages Mackup configuration.
    ~/.mackup.cfg:
      path: .mackup.cfg

    # These two launchctl agents are only required on Mac OS
    # to make gpg-agent play nice with ssh auth in apps that don't start
    # from shell with it's environment.
    ~/Library/LaunchAgents/homebrew.gpg.gpg-agent.plist:
      path: Library/LaunchAgents/homebrew.gpg.gpg-agent.plist
    ~/Library/LaunchAgents/link-ssh-auth-sock.plist:
      path: Library/LaunchAgents/link-ssh-auth-sock.plist

# If you want to run any commands right after the dotfiles setup is complete,
# you can do that here.
# For example:
# - chsh -s $(which fish) to setup your shell, assuming fish is installed.
# - vim +'PlugInstall --sync' +qa to istall vim plugins, assuming you use vim-plug to manage them.
- shell: []

Making a `Brewfile`

Homebrew has a mechanism to dump all your installed packates into a Brewfile:

# brew bundle dump will make a Brewfile in the current directory,
# but you can explicitly give it a path with --file flag.
brew bundle dump --file ~/src/dotfiles/Brewfile --force

The resulting file will include:

Homebrew native packages that you installed manually that are not dependencies of other packages. If you're making a new Brewfile on an existing system that has a few years of cruft on it, you might want to review your Brewfile and only keep the packages that you want on your new system(s).
List of all Casks installed — that's why I prefer to install as much software as I can with Homebrew. A lot of applications can be installed via Casks: Zoom, Firefox, Slack, Fantastical, Spotify to name a few.
Homebew also has a way to bundle all of the applications that you installed via Mac App Store called mas. For App Store apps to be included, you will need to brew install mas before you brew bundle dump.

Note: Brewfile is in the dotfiles repository, but it will not be symlinked into the target system with dotbot.

Backing Up Various Mac-Specific App Settings With Mackup

Mackup is a neat little backup utility for Mac computers that can backup a lot of applicaation specific and system settings that don't quite fit into dotfiles. I think it's intended to be used standalone, and by default it would attempt to backup into Dropbox, if it detects that it's available. But you can backup to any directory you want, and I prefer backing up into my dotfiles repository.

To only backup the app settings that you want, you can do the following:

brew install mackup
Create a .mackup.cfg file in your home directory. I prefer to backup this file with dotbot as well.
Run mackup backup.

Be careful about what you mackup. Some applications, like VSCode, prefer to sync their configuration to a cloud on their own, and that can mess things up a little bit — you'll end up with forever dirty dotfiles working copy.

Here's my configuration:

[storage]
engine = file_system
path = src/dotfiles
directory = mackup

# These applications are managed by dotfiles themselves,
# No need to re-link them to mackup
[applications_to_ignore]
# I don't like symlinking vscode settings personally.
vscode
starship
netrc
yarn
neovim
tmux
fish
git
vim
zsh
mackup
ssh
gnupg
ansible
skhd
yabai

As a nice example, mackup backs up your Xcode keyboard shortcuts!

Restoring on a New Mac

Restoring is straightforward, and essentially walks the same steps as the backup:

Get SSH keys to work so you can download your dotfiles.
dotbot install — that gets you the barebones of shell settings and other niceties. It also gets my gpg to work in my case.
brew bundle install will install all your Homebrew packages, casks, and App Store applications. This will require that you sign in with your Apple ID in the App Store app. You don't have to have the same iCloudID that you had when you purchased the apps, as long as the Apple ID that you're using has those apps purchased too.
mackup restore to get the rest of the apps and settings.

What's Not Covered?

I'm still looking for a way to backup some Mac-specific system settings — please @ me if you know how to get them backed up in an elegant way. Perhaps I should shove them into the shell section of dotbot config for now:

Mouse and Keyboard settings like key repeat interval and mouse sensitivity.
Dock settings (put Dock in the left side, autohide: on).
Screenshot directory settings, including creating a ~/Screenshots and putting a shortcut to it to your Dock.
Disable all interface sounds.
Disable all/most UI animations.
Disable Keyboard input autocorrect and auto-capitalization.
Add Keyboard Input sources (yay Russian).
System keyboard shortcuts like Spotlight and changing input sources.

I believe they all are possible to setup with defaults write something something, but I'm too lazy to do that.

Barebones Engineering Management Interview Questions

nate@respawn.io — Tue, 29 Nov 2022 00:00:00 GMT

Barebones Engineering Management Interview Questions

At the core, engineering managers are accountable for two things: delivering projects, and supporting their teams. But they can operate on different levels, from constant firefighting to building resilient systems and tuning them.

Just like most small companies can't afford hiring and training junior engineers, most small companies can't afford hiring and training junior engineering managers — training them is much more expensive and complex.

So you want managers who can operate at least on the most basic level autonomously, who already made some mistakes, and have seen some situations in their managerial career, and learned from them.

Shipping software

Tell me about a project that went horribly wrong, and what did you do to steer it to success? Planning is educated guessing. When a project's plan blows up, you want your managers to communicate clearly, actively align with other teams, adjust plans, all while creating a safe environment for engineers to speak up, raise risks, and learn from the situation.

This is stressful work. And managers become better at this with experience. If a candidate says that all their projects are always on track, and they never had a problem, then either you just found a unicorn, or they're very junior.

Dealing with low performance

Tell me about a situation when you had to support an engineer who wasn't performing well. Providing negative feedback is awkward and hard. Receiving negative feedback is the same. There's so much you can get out of this question:

How does a candidate deliver feedback?
How does candidate support engineers who need help? Do they just pip them and call it a day? Do they ignore them for a year and hope they improve on their own?
What are the specific systems that this candidate put in place to improve engineering performance over all in their team?
What did they learn from an awkward and challenging situation?
How empathetic and vulnerable are they?

I'm usually looking for candidates that can open up, admit this area of work is genuinely hard, and admit they've learned a lot, and are still learning, and show me specific examples. It's okay if they're emotional, or nervous around this topic.

Again, I'm usually looking for folks who can share stories and go into details in follow up questions. If a candidate tells you that they had an underperforming engineer, ran a single performance review, asked someone to pair with them for 3 weeks and that solved the problem — they're very junior.

Building trust in the organization

The two areas above are the bare minimum for operational work of an engineering manager. If there's a project blowing up, or an engineer on the team lost motivation, a manager might switch into firefighting mode and take care of the situation. New eng managers can spend quite a lot of time in firefighting mode.

But good engineering leadership is more than that — it's about building systems (of relationships, trust, communications, and plans) that support your teams and other teams around.

How do you provide a clear view into your team's work and roadmap for other teams, and for leadership? At certain point, your leadership team is going to ask your boss to ask you what the hell are your engineers doing. How do you provide visibility into their work, without demanding that they submit their pull requests every week?
Tell me about a situation when you helped your team understand and work through a significant unexpected change in your company. Good managers listen around, get information early, package it up in a way that's easier for their team to process. Take the outside chaos and digest it into calmness. Good managers know what's important to talk about in a safe team space, and what can be just posted in a company-wide email.
Tell me about a situation you worked with your peers in other organizations (product, design, customer support) on an organization-wide change / process that affected multiple teams. How did you design the change? How did you ratify it and get it approved? How did you implement and roll out the change? It's extremely hard to get to agree 10 people in different departments that 2 × 2 is 4, let alone commit to a new process. If the candidate did attempt a change, they will have invaluable lessons out of it.

Bigger picture

The scope of enginering management work is so wide that it's hard to define in an article, let alone design an interview loop that would surface signal around all the things managers do. The best short overview I found is in the Engineering Manager's Bill of Rights.

The list has 8 bullet point, each of them covering a broad area of work. In a given 45-minute interview, you have time for one topic with follow up questions, or maybe two separate questions. Even assuming one qustion is enough to get the signal on one area of work, that's 4-6 interviews, easily.

Neither most startups, nor candidates can afford to invest in 6 interviews. You'll have to figure out what areas are important for you, your teams, and your companies, and build your interview loop around them, and make decisions with partial, and flawed, data.

Training, Coaching, and Mentoring as An Engineering Manager

nate@respawn.io — Tue, 23 Aug 2022 00:00:00 GMT

Training, Coaching, and Mentoring as an Engineering Manager

A big part of your job as an engineering manager is to figure out who to spend time with, what role to play in a relationship with that person, and how to support them best.

Whether you're an individual contributor, a team lead, or a manager, you'll have plenty of opportunities to work in each of these roles.

Training

Training your hires to do their job is usually a part of their onboarding process. Training applies to the basic building blocks of what the person does in their role, and sets up the core knowledge about the tools they are using. You can run training programs to get folks up to speed with the frameworks and tech stack you're using; you can train folks to use shipit to deploy the code to production, use datadog to see what's happening with that code in production. Training brings the knowledge of where the knobs and buttons are.

Usually, you would not train each of your new hires individually. Instead, you build onboarding documentation, projects, and delegate some training to onboarding buddies — other folks on the team who know their way around your stack.

Coaching

Coaching is the second layer: the person knows the technology and the tools, now you show them how to get things done using those tools. The part that's not in the manual.

Coaching is like training: you're teaching folks to be successful in their role. You're still setting the agenda, the coaching plan, and highlighting the areas they need to cover, based on how you see the person show up. But, coaching applies to aspects of the role that require more creative thinking:

You coach your senior engineers to lead a project, if you're grooming them to become a team lead.
You coach your engineers in working with folks in product and design teams to get things done faster.
You coach your engineers in asking the right questions when they are design the system, so they don't have to rewrite it from scratch a year from the initial release.
You coach your engineers to improve their communication and people skills, especially in remote work environment: when and how to ask for help? How to check-in with others? How to keep folks updated on what you're working on?

The more you coach people on the team, the more they form intuitions and "gut checks" in a wide range of possible work situations. Coaching lifts people, and levels up your team.

You need to lift others to grow as an engineering leader. If you find yourself jumping into code often, because "no one has the gut check to jump into the right area and fix things quickly", and you want to be the safety net for your team — you're effectively spending time on a one-off problem, instead of coaching your team on how to deal with problems like that in general.

If you don't coach people on your team well, you will not see a whole lot of progress. Sure, your team will ship projects, but they won't gain velocity and experience at the pace that they could. And you're going to be stuck. It just makes you a bad manager.

My regular self-assessment questions:

Does everyone on my team have a clear, written growth path and a plan for this year?
What are the specific things that I'm doing to help them progress in their plan this month?
If I want to scale things up, what are the patterns or commonalities that I see in the plans for members of my team?
What am I doing to put systems in place that would support people with similar milestones, instead of coaching "from scratch" every time?

Mentorship

Mentorship is like coaching, but it's driven by the mentee. They set the agenda. As a mentor, you help someone navigate situations that are new, curious, or tricky for them. You help them see what happens next, align their goals, and learn from the situations. Your help as a mentor spans wider than their immediate role in your team.

Be very intentional about your commitments to mentor people. You can't mentor everyone — you will meet people in your career who you're fine working with on your team, but you just can't be their mentor.

Being someone's manager, you have the power to define their path and career trajectory. If someone's long-term career goals are not aligned with what you think you need on your team in the next year, you don't have the immediate incentive to mentor them.

Put people first. Always. Mentoring folks on your team towards their personal, career goals, is what creates strong relationships that ascend beyond companies.

If someone on your team wants to work towards a new skill that you might not immediately need in your current org — be upfront about it, and see if you have the energy and time to mentor them towards it.
If someone asks for more mentorship than you can give — reach out to your network and help them find the right people to support them, outside your organization.
Building the right mentoring relationships always pays off. It makes all the difference between you being an average manager (for that person), and you being the best manager they've ever had. If you're an early stage startup that relies on referrals in sourcing candidates, you better be an excellent mentor.

Learning to be a better leader

You don't expect a new manager to excel at training, coaching, AND mentorship, all in their first year of managing a team, the same way as you don't expect your intermediate software engineer to lead a complex project that spans across 4 teams.

Even as an individual contributor, you will have opportunities to train people on your team.
- As an individual contributor, your training is focused on one person, not a full team.
- Maybe you train others as an onboarding buddy.
- Or maybe you mentor engineers from other teams in your tech stack that they're curious about, if your company has a dedicated mentorship rotation program.
Once you become a people manager, your job is to support your team, and be accountable for delivery.
- Yes, if the projects are not shipping on time, you're in trouble. But you also have your first year to figure out the coaching piece.
- Unlike in an IC role, you're now responsible for training and coaching your full team.
- Coaching intermediate engineers is more straightforward, because you have a clear direction — they're expected to advance in the career leveling ladder, and you're expected to help them.
- Coaching senior engineers takes more time and attention, but has much bigger impact.
Once you get more experience as a manager, you'll get to build coaching and mentoring relationships, and partnerships with your senior and staff engineers.

Hopefully, while all that is happening, your manager is coaching you to be a better leader for your team. Once you soak up enough experience, you'll be ready to coach team leads and managers of your own.

Structured Learning

nate@respawn.io — Mon, 08 Aug 2022 00:00:00 GMT

Structured Learning

A few months ago, I found myself stuck:

To become a better leader for my team at Zipline, I need to learn to work with larger organization scale, to hire and coach engineering managers.
To get closer to my dream of a quiet life of an indie developer and a solo founder, I want to learn more about building iOS apps.
To build up my career security and career compensation, on top of learning to manage larger orgs, I need to build up experience working with more robust, reliable systems at scale, and do more infrastructure work.

These are three distinct directions. Leading a team (or teams) and having a 2 year old kid doesn't leave a lot of time to invest in learning. If you're anything like me, the monkey brain will happily jump to any new exciting engineering topic, not leaving enough space for the new knowledge to crystalize in your head.

Bringing structure to your learning means to make trade offs about what to tinker with first, and consequently what to put away for now. With some structure in place, you should be able to see what your new skills and knowledge would shape into in a few months from now.

Learning one thing means not learning another (for now)

What would you say to someone else struggling to fit 20 hobby projects into their schedule? This topic often comes up in 1:1 conversations with my team, and the advice is usually something like this:

Figure out what you want to do, and why you're interested in doing it.
Think about how much time you want to spend on it. Timebox it, but make an estimate of how much time you need to spend for a meaningful outcome.
Think about what other areas you're interested in — how much resources and time do they need?
Now you can reason about the trade offs: if you're committing time to work on project X, what are the projects you're committing to not doing?

%% The big lesson of looking at your learning from this angle is that you only have enough time for a few topics each year. Making the right choice will bring you lots of fun, and can change your career trajectory dramatically. %%

You only have 5 months left in 2022. Each new skill you want will take at least 2 months to develop. What are the skills you want most, and what's the type of work that you need to do to acquire them?

This approach might look clean and nice in theory, but in practice it means that now you have a new problem: instead of working on a project right now, you have a new meta-project of exploring time commitments and trade offs. It's up to you to decide how much time is reasonable to spend on this.

To me, it's proportional to the size of the commitment: if I'm about to take on a year-long project, I would spend a couple weeks to make sure I'm ok with not doing other things for a year, and in what situations I can drop the ball. But if I'm committing for a few weeks, a couple hours session with a notebook is fine.

Learning SwiftUI in July

Which brought me to what I did in July! I've spent my nights tinkering with SwiftUI, inching closer to two toy projects that I want to build.

Why: I wanted something hands-on, something I can build and see the results of it. Something applicable to my current work: spiking on using SwiftUI to build simple forms and flows gives me deeper understanding of what part of my team is working on. Engineering managers write code, a lot, but not to build features. We code to learn the trade offs our teams are facing.
What: started with wrapping up a course on SwiftUI that I've started previously. I love having things done done, and this one was hanging in the air for a year. I've picked up a couple of courses as a result of this month-long exploration, though.

Tinkering with Swift is on hold for August. I miss it, a whole lot, but it's time to read up on building reliable and robust platforms, and on leading larger, more diverse teams.

Levels of Engineering (Management) Focus

nate@respawn.io — Sun, 03 Jul 2022 00:00:00 GMT

Levels of Engineering (Management) Focus

Ok, here's another way to think about going back and forth between engineering management and IC engineering.

Obligatory reminder: engineering management is not a promotion, it's a totally different role that requires a different set of skills. More companies have figured this part out, and senior engineers can level up into tech leads, staff engineers, OR engineering managers. If things are done well, staff engineer and eng manager should have roughly the same compensation bands, so that the management path does not automatically mean more money, and it's not the only way to make more money.

I've been thinking about going back to building things myself. And I'm not the first to argue that folks with management experience make great engineers, and vice versa!

So here's the thing. As an engineering leader, you can focus on different levels in your company. Each level requires a different set of skills and (fresh) experience:

Narrow: focus on supporting and growing your team, and working on a specific set of problems with your team.
Wide: as you become a senior engineering manager or a director, the best way to support multiple teams is to talk to the other orgs in the company, figure out what is happening, and how to best help them hit the company goals, then guide your eng managers towards that.
IC: there's nothing stopping you from hyper-focusing on a narrow, specific problem as an individual software engineer. Your experience deteriorates with time, and as you get more senior, switching between the different roles of software engineer and a manager becomes harder. But if you have a strong internal support network in your org, and if you're OK moving laterally or down level, it's totally fine to switch back to IC.

Onboarding as a manager, or a senior engineer, takes a rather long time. To be productive in a role and to grow, you would need about two years at a single gig. Which means that you don't really have that many switch opportunities in your career.

Choosing to switch back to building software also means that you're likely giving away becoming a VP. But going into exective leadership is a deliberate choice. Just like continuing to build software yourself. And to be a great engineering leader, you do need to work on your skills as an engineer, so maaaaybe switching your focus to a full-time IC role is a good tool, as long as it's deliberate, and you have the opportunity.

New Site! Obsidian, Next.js, and Vercel

nate@respawn.io — Thu, 16 Jun 2022 00:00:00 GMT

Obsidian, Next.js, and Vercel

[!warning] Contentlayer is kinda half dead. Stop bolting things together, [[2025-time-for-a-rewrite|just use Astro]].

Here's how this thing works:

The source repository is open.
It's based off Next.js static gen blog starter kit. Tailwind for markup. First time I use either of those. But hey, I have an execute program typescript course sitting for 6 months, and I need to spike on a few typescript things at work anyway.
I'm using Obsidian for my notes, and decided to try and use it to write the blog, too. I then ln -s path/to/obsidian/vault/respawn.io/* to the content directory. This should work for any static site generator.
Markdown is rendered using contentlayer and it's great.
Analytics is on Vercel's side, out of the box.
Opengraph images are generated with @vercel/og. This feels like dark magic and I have no idea how it works, but hey, it works. Here's an example for this post:

RSS feed is rendered with feed library using a script in scripts/rss.ts, invoked with tsx. Images in the RSS feed are base64-encoded and inlined.

Caveats

Images are generally stored in the content directory, side by side with a post.
- All .png images are copied over from ./content/**/*.png to ./public/ in a build step by scripts/copy-images.sh. That way, both the compiled website, and Obsidian vault can have nice images without too much hassle with paths.

Same Markup, Different Presentations

Over the months, I've changed a few things, and mostly it was fun to hack on. I want most of the Obsidian features to work seamlessly in the notes that I publish. Links, callouts, footnotes, perhaps tables, images. Some of that is now solved, but there are more things on that todo list:

Content for pages, posts, and daily notes is [[contentlayer-with-multiple-data-types|generated with Contentlayer]].
There's some additional code that allows for MDX processing of the fields in the front matter of posts.
Callouts. Early on, I've had a custom <Callout> component that I've fed to MDX, but that would mean that the note in Obsidian has the Callout block that doesn't actually represent a Markdown callout, or a callout block Obsidian would understand. So I've switched to Obsidian-friendly callout format in this commit
TODOs. remark-gfm mostly takes care of that, so I can have todo items with checkboxes in both Obsidian, and in the rendered blog with GitHub-flavored Markdown syntax.
Footnotes. I want to be able to have footnotes that render as an aside on desktops, but that show up in the usual footnotes section on smaller screens.
Tables. Obsidian 1.5 made a great UI on top of Markdown tables, so you can actually use them. I'd love to use tables in my posts, but that might be tricky in mobile layouts, though.
Diagrams. Obsidian supports Mermaid diagrams out of the box, and adding them to the site is relatively straightforward. Implemented! Details in [[contentlayer-mermaid-diagrams|this post]].

Content Types

Daily notes. I've added daily notes to be able to write and send quick, small notes, and not think twice about them — and they're fun. But now I think it's time to set up the routing, so I can link to one specific daily note.
Tags and topics. There's enough content to add topics, and support "native" Obsidian tags.

UPD 2025: Diagrams

Here's an example Mermaid diagram that would render both in Obsidian and in the post correctly. It's rendered in both light and dark mode, and the right one isshown conditionally!

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

You can [[contentlayer-with-excalidraw|embed excalidraw diagrams as inline SVG]] too!

![[contentlayer-with-excalidraw 2025-03-30.excalidraw]]

Natik's Journal

This Thing Finally Looks Nice, Clean, and Calm

Homepage

Post

Topic

Slopware of The Month

How I Got Hired

How I got hired

Evil Martians, 2010

Retail Zipline, 2021

Airbyte, 2023

Apple

Sentry

Airbyte

Lambda

Time for A Rewrite!

Slow and Has a Soul

Slow and Has a Soul

Companies by the vibes

Remote work approach

Airbyte

Raycast

How does the math look?

The Dream

How to Get Promoted Faster

How to Get Promoted Faster

Take ownership of your career

The growth plan

The brag list

The promotion package

The Natik User Guide

The Natik User Guide

Daily Schedule & Work Habits

IRL

Communication & Collaboration

Supporting My Team

Feedback to Me

Failure Modes

Natikisms

Setup Zed Ai Assistant with Deepseek V3 on Lambda

Setup Zed AI Assistant with DeepSeek V3 on Lambda

Why bother switching from Sonnet?

Zed AI Assisant configuration

Bonus

Pattern Recognition

Pattern Recognition

How to Embed Excalidraw in MDX

How to Embed Excalidraw in MDX

Obsidian Setup

Embedding drawings in Obsidian

Rehype Plugin

Airbyte in 2024: Better Extensibility Primitives

Airbyte in 2024: better extensibility primitives

What is Airbyte again?

♻️ Extensibility Feedback Loop

Here's what we've shipped in 2024

550+ connectors

Connector Builder: Everything-to-no-code

Connector Builder: Fork & Contribution Flows

Connector Builder: AI Assist

Connector Tooling and Automated Maintenance

Progressive Rollouts

Airbyte CDK Performance

OAuth apps support on Airbyte Open Source

Airbyte CDK is more open now

Vector Store Destinations

Airbyte 1.0

abctl

PyAirbyte

I'm hiring btw

Mermaid Diagrams in A Static Site Using MDX and Contentlayer

Mermaid Diagrams in a Static Site Using MDX and Contentlayer

Content in *.md to MDX: Contentlayer

MDX to SVG: Rehype Plugin

Using Puppeteer with headless Chrome on Vercel

Light and dark mode support

Follow-up: Excalidraw next?

Ghostty Is Awesome

Ghostty Is Awesome

Configuration Caveats

`abctl`

`PyAirbyte`

Content in `*.md` to MDX: Contentlayer

How to Get `iso639.2` Locale Code in Swift

Make an `appiconset` with CandyIcons asset generator