Andrew Stiefel

Building a personal monorepo for writing

2025-07-19T00:00:00-07:00

I use Obsidian to organize my thinking and writing. But I’ve always been dissatisfied with the process of turning what I write into a formatted post for my website. I either had to manage multiple vaults—adding complexity and violating one of my core principles of note-taking—or copy, paste, and edit my writing in another tool like VS Code.

I also prefer to keep my content separate from the website’s design, and I wanted to do that without introducing a CMS or additional tooling. Static site generators like Jekyll are great at converting Markdown into websites, but they usually require you to store content alongside all the other website files.

After some experimenting, I landed on a better solution: building a personal monorepo for my writing and publishing workflow.

Why use a monorepo?

A monorepo—short for monolithic repository—combines code for multiple projects into a single repository. A common pattern is to store both frontend and backend code in one place.

That’s actually a good analogy for how I think about writing. The “backend” is my Obsidian vault, where I research and take notes. The “frontend” is the website where I publish finished posts.

Basic Setup

To start ,I moved my Obsidian vault and Jekyll website into a new personal-monorepo directory structured like this:

~/personal-monorepo
├── /notes
└── /website

If you don’t already have an Obsidian vault or Jekyll site, you can easily replicate this from scratch. Install Obsidian, open the /notes directory using the “Open folder as vault” option, and you’re ready to go.

Setting up Jekyll requires a bit more technical work, but you can find installation instructions here.

Configuring Obsidian

For this approach it’s important to make a directory where you will only store published posts. I’m going to use /notes/posts for this tutorial but you can configure this directory any way you wish.

I also recommend installing two Obsidian community plugins:

Obsidian Git – adds version control and makes publishing easy
Obsidian Permalink Opener – lets you open post URLs in your browser for previewing

For Git, you can push commits manually or set up periodic syncs. For the Permalink Opener plugin, I added both my website’s base URL and my local development URL so I can preview posts in the browser while editing.

With that we’re ready to move on to building our website.

Connecting Jekyll and Obsidian

By default, Jekyll looks for posts in /website/_posts. But I want it to use the content in /notes/posts. The simplest solution is to create a symbolic link.

First, open Terminal and make sure you’re in the root of your monorepo (~/personal-monorepo). Back up your content, then delete the existing _posts directory:

rm -rf website/_posts

Next, create a symlink that points to your Obsidian posts:

cd website
ln -s ../notes/_posts _posts

Note: Folder names in symlinks are case-sensitive. If your Obsidian vault uses Posts instead of posts, your symlink won’t work with the above command. Folder names must match exactly.

Publishing with Netlify

Netlify provides first-class support for working with monorepos, but you’ll need to do a little additional configuration.

In your project dashboard or netlify.toml file, set the base directory to website, and make sure the build command installs dependencies before running Jekyll:

Here’s what my full netlify.toml looks like, and what is reflected in my dashboard:

[build]
  base = "website"
  command = "bundle install && bundle exec jekyll build"
  publish = "_site"

Netlify follows symlinks automatically, but Jekyll needs one extra setting. In your website/_config.yml, add:

# Enable access to symlinked content
lax_symlink_lookup: true

This lets Jekyll access files stored outside its root directory (e.g. the website folder). Without the site will build but won’t pull in your content from the notes/_posts directory.

Final Workflow

I have Obsidian configured to add new notes to my writing inbox under the ~inbox directory. Anything I start writing goes there. Once I’ve finished writing a note, I can then either move it into my permanent notes or add it to the posts directory if I want to publish it. Once I push the commit Netlify will build and publish my site.

While I’m writing, I can preview what the note will look like by starting the Jekyll development server (bundle exec jekyll serve) and adding the note to the posts directory. I can use the Obsidian hotlinks command to open a preview of the post in my browser.

To wrap up, your final workflow looks something this this:

Write, edit, and link notes in Obsidian
Commit and push changes to Github
Netlify will pick up the changes and publish your posts

Bonus: Convert Backlinks to Weblinks

It’s outside the scope of this post, but I also wrote a custom plugin to convert backlinks to web links. That way I can use Obsidian’s backlinks within my published posts.

You can grab the code here.

Additional Resources

AI isn't taking your job — the economy is

2025-05-16T00:00:00-07:00

Have you noticed the latest trend sweeping executive suites? This year, layoff announcements are getting blamed on AI. Or maybe it’s employee performance. No — it’s definitely AI.

But if you look closer, you’ll find a more familiar culprit: the economy.

Companies don’t want to admit revenue is slowing or that fundamentals are crumbling. It’s easier to say they’re “embracing AI” than to admit they’re under pressure to cut costs and protect margins.

Yes, AI is changing how we work — especially for junior roles in software development, sales, content creation, and support. But the wave of layoffs sweeping tech, healthcare, and biotech isn’t being driven by machines replacing humans. It’s being driven by elevated interest rates, post-Covid revenue declines, and investor pressure to do more with less.

AI just provides a convenient cover narrative.

A Correction Disguised as Innovation

Several major tech firms — including cloud providers, social platforms, and enterprise software giants — have collectively laid off more than 600,000 workers since 2022 according to Layoffs.fyi.

These cuts impacted recruiting, HR, operations, marketing, and in some cases engineering. Companies that ramped up quickly during the pandemic suddenly found they were overextended in a post-zero interest rate policy (ZIRP) world. Capital became more expensive. Growth expectations took a cut. And investors needed to see profitability instead.

This is a Covid-era bubble correcting itself. Most of these companies are still larger than they were in 2019. In fact, as research by the Pragmatic Engineer has shown, software engineering in particular has experienced a boom and bust.

The change in the number of listings in 2025, compared to 2020, for each of these areas:

All jobs: +10%

Banking and finance: -7%

Sales: -8%

Marketing: -19%

Software development: -34%

Overall hiring has mostly returned to 2019 levels. There is a hesitation to hire more, but that’s partially due to uncertainty about the level to hire for with AI and ongoing uncertainty about macroeconomic conditions.

From Tech to Biotech: The Narrative Spreads

Like any good pathogen, narratives like to spread. And this one is jumping from Silicon Valley to biotech and healthcare – the other industries most impacted by Covid-19.

A large mRNA vaccine manufacturer recently announced that it was merging the CTO and Head of People into a new Chief People and Digital Technology Officer role. The stated reason? To identify which roles are best suited for AI vs people.

But they are following a now-familiar playbook:

The company reported a GAAP net loss of $1.1 billion loss in Q1 2025
Revenue from Covid-era mRNA vaccines continues to fall
They have reduced operating costs by 19% to compensate

Behind the scenes, it’s facing post-pandemic revenue decline and investor pressure to reduce costs. So they’re turning to layoffs — with AI as the smokescreen.

So what is AI doing to jobs?

There is no question AI is changing work. I use AI in my job nearly every day. And it’s definitely impacting the labor market. A recent study found that:

Junior developers experienced 27-39% productivity gains using AI coding tools.
But senior developers saw smaller productivity gains, typically 8-13%.

AI enhances speed, but doesn’t replace deep expertise yet. In fact, the more you know about a subject or field the less magical it is.

Unsurprisingly, entry-level roles are the first to feel the effects: SEO writers, junior engineers, SDRs, and support teams. But the scale is smaller than the headlines suggest.

Even firms that proudly touted major AI-based role reductions have quietly reversed course — reopening hiring in those same departments just months later.

The Bottom Line

Companies aren’t laying people off because AI is replacing them. At least, not yet. If you’re familiar with AI technology, you know both how far and fast it has come — and all the countless ways it hallucinates or falls flat. It makes a great assistant, but a lousy replacement.

So don’t mistake narrative spin for a technological inevitability.

AI isn’t coming for your job. Because the CFO already did.

Disclaimer: The views expressed in this post are my own and do not reflect the opinions or positions of my employer. Company examples have been anonymized to focus on trends rather than individual firms. All references are drawn from publicly reported data.

How I use GitHub as a CMS

2025-02-02T00:00:00-08:00

I use Jekyll to build and publish my blog on Netlify. For a long time my content management system (CMS) was just a bunch of markdown files on my laptop. Most of the time I don’t need anything else — it’s simple, and it’s just me.

But as I’ve wanted to focus on writing more often, I wanted to find an easier way to track future ideas, what I’d like to work on now, and easily see what I’ve done.

That’s where GitHub comes in.

Why?

GitHub is built for software development, but many of the features work just as well for content development. In fact, is has about everything I need as you’ll see in my setup section below. This includes templates, project boards, and workflows for publishing.

Plus it’s easy to review and collaborate with other people. I don’t do that much as a solo writer, but I do get readers who spot typos or who share feedback—and then it’s easy to track and add their contributions.

But let’s be honest — this is one of the projects I took on because I could, not so much because it really saves me any time. Choose your adventure accordingly :)

Basic setup

If you’re already using GitHub to host the code for your blog (like I do with Jekyll), then you can get started with this in 15 minutes or less!

Create a project: Go to the GitHub repository for your blog (or make a new one!) and select projects and create your project.
Choose a format: GitHub projects lets you customize views of items in your project using a Kanban board or table format. I recommend starting with the Kanban format. You can always change this later.
Organize your workflow: Once you’ve created your project, take a couple minutes to configure your workflow. I have sections for no status (my backlog), in progress, ready, and done.

You can see an example of mine on GitHub, or with the screenshot below:

Use issues to track posts

Once you’ve created the basic structure, it’s time to start tracking your writing! You’ll want to create new issues so you can track your progress. I decided to create a new template so I wouldn’t have to add the same info every time.

If you’d like to create one, all you need to add is a markdown file in your repository at the location below:

.
├── .github 
│   └── ISSUE_TEMPLATE
│      └── cms.md

Here’s an example of what mine looks like:

---
name: cms
about: Submit an idea for the blog
title: "[blog post] "
labels: cms
assignees: ''
---

**What is this post about?**


**Outline**
1. 

**Tasks**
- [ ] Write outline
- [ ] Draft blog post
- [ ] Find (1) reviewer
- [ ] Create pull request

I use the format [blog post] example title so I can see at a glance that the issue covers a new blog post, and roughly what it’s about. I provide a brief description (usually when I first have the idea). Later I’ll come back and outline the post.

Writing and publishing posts

Jekyll comes with basic structure which makes it easy to get started. I save my draft writing in the _drafts folder and move finished posts into the _posts folder.

.
├── _drafts 
├── _posts

But you have a few options to customize your workflow a bit further:

Work directly in your main branch and publish by moving the your finished drafts from the _drafts folder to the _posts folder.
Create a new branch for each post as you work and merge into your main branch when you’re ready to publish.

JEKYLL TIP You can preview your posts in your development environment as you work! Just append the --drafts flag to the build or serve command. For example, jekyll serve --drafts. Each draft post will be added using the last modified time as the publication date.

I prefer to create a new branch and to submit a pull request when I’m ready to publish (although I’ll admit, I’m not super consistent since it’s just me). Either way, when you’re ready to publish, you’ll close the issue for your blog by writing a commit message that includes the number of the issue. For example, when I published this blog, I used “Closes 212” to tell GitHub to mark the issue as done.

Now if you visit your project, you’ll see your post has automatically been moved to the “done” column!

Final thoughts

I’ve been exploring ways to customize this further by creating new views — for example, a table view that adds publication dates so I can when I want to publish a post. But most importantly, I’m enjoying the flexibility and close integration between what I write and how it’s published.

Markdown files, not apps

2025-01-17T00:00:00-08:00

Files, not apps. I’m convinced this is the best way to work in the future.

I write down almost everything important in my life: lists, ideas, plans, code, and articles. They form my extended memory. They are a record of what I’ve done, and who I’ve been. That’s why I only use markdown files.

Traditional document and note-taking apps like Word, Evernote, and Notion create data silos and vendor lock-in, limiting your ability to freely move and process information.

I discovered this the hard way when I tried to move between different ecosystems like Evernote and Apple Notes. Sure, there was a way to export my data. But it was a mess. Things broke, attachments went missing, and I spent hours converting, reformatting, and importing.

Markdown is simple

Markdown files solve these challenges through their fundamental simplicity. Any text editor can open and edit them, eliminating dependency on specific applications or platforms. They have all the basic formatting you need for headlines, bullets, lists, and even basic tables.

Markdown is portable

If you use Evernote or Notion, for example, you are helpless without them. If they go out of business you are trapped and have to move your files to another format. You will outlive those companies. I’ve already outlived a few note-taking companies.

I can work with markdown files on any device, forever. I can access them with any text editor I want. This makes them remarkably long-lived. Proprietary formats come and go, but markdown’s open, plain text nature ensures it will likely outlast me. This makes it the ideal format for building a personal knowledge base.

Markdown works offline

There are times when I want to be offline and unreachable, but would still like to jot ideas down in a format that is easily searchable. Working offline is an amazing productivity boost. Why give that up for an online database?

Markdown is ready for AI

This is a use case I wouldn’t have imagined a few years. But it’s the main reason I’m convinced markdown files are the future. Since markdown is just text, AI systems can easily process and analyze your notes.

For example, I can easily grab my “Ideal Customer Profile.md” file and throw it into ChatGPT, Claude, Gemini, or whatever I’m using at the moment to work with it. I can add my messaging framework, and immediately start brainstorming marketing copy.

I can run a local LLM, point it at a folder of my markdown files, and then interact with my notes by asking questions. It’s like a personal assistant built on everything I’ve learned and experienced.

Conclusion

Everything I write is human readable, and yet actionable with apps and tools. I always have my files available locally, and backups are just making a copy of the folder and putting it somewhere safe.

Markdown is simple, portable, independent, and free — exactly how I want to live.

Principles of platform independence

2025-01-10T00:00:00-08:00

The internet is filled with stories of people breaking free from Google’s ecosystem (here are a few examples I’ve seen recently). Yet in their rush to escape one tech giant, many users inadvertently chain themselves to another.

I’ve noticed a paradox on social media: people who champion digital independence while relying heavily on platform-specific tools like Apple Notes or Passwords. They overlook how Apple, like Google, builds its business model around service lock-in – from iCloud storage to annual hardware upgrades.

Personally, I prefer to maintain platform independence as much as possible. Over the years I’ve developed a set of criteria — let’s call them principles of platform independence — for choosing what apps and software I use. This way I retain control over my digital life regardless of which company’s software or hardware I use.

1) Cross-Platform Compatibility

Use applications that work across different operating systems (MacOS, Windows, Linux, etc.) to avoid being locked into one platform’s ecosystem. This ensures your workflow remains consistent regardless of the device you’re using.

2) Data Ownership

Choose applications that allow you to easily export your data in formats that can be read by different applications. You should have full control of your data, and it should be accessible in a readable format outside of the application.

3) Data Portability

Beyond just being able to export data, it should be in widely-supported open formats (like CalDAV for calendars, IMAP for email) rather than proprietary ones. This enables interoperability and switching between different clients.

4) Logic Separation

Your data shouldn’t be tightly coupled to specific application features. For example, your notes should be stored in a format that preserves basic formatting even if specific application features aren’t available elsewhere.

5) Local Control

Whenever possible, you should have direct access to your data in a readable format on your local system, not just through a cloud interface. This includes the ability to make local backups. I like to keep a version in the cloud, a version on my local system, a local backup, and a remote back up.

Dead internet is no longer a theory

2025-01-03T00:00:00-08:00

Dead internet theory suggests most of the internet’s content and traffic is artificially generated by bots rather than humans. The conspiracy theory emerged amidst the fallout of the 2016 election, when news broke about websites creating fake news to gain clicks on Facebook and Google and leveraging bot accounts to amplify it.

Ironically, Meta decided to turn the conspiracy theory into reality.

Meta looks into the black mirror

Quoting from 404 Media:

Earlier this week, Meta executive Connor Hayes told the Financial Times that the company is going to roll out AI character profiles on Instagram and Facebook that “exist on our platforms, kind of in the same way that accounts do … they’ll have bios and profile pictures and be able to generate and share content powered by AI on the platform.

It didn’t take long for users on Blue Sky and Reddit to find some of these fake AI profiles on Instagram. The profiles were often offensive caricatures of what a gigantic corporation like Meta might imagine a “proud Black queer momma of 2” might post about. The profiles tended to post AI generated content similar to what other spammer’s on Meta’s Facebook and Instagram platforms have been creating.

Here’s the example I referenced above:

Most of these profiles were already a few years old, and Meta has since announced that they will be taking them down.

Dead internet theory gained traction online because it speaks to genuine concerns people have about authenticity and the increasing use of bots and AI online. I have no idea how anyone at Meta could think launching this exact thing would be a good idea.

I also suspect these profiles will still get rolled out in the future. But next time they won’t have the “AI managed by Meta” labels attached to them.

Navigating the dark forest

So where to from here? We’re entering a new dark forest where it’s increasingly difficult to find the humans among the trees. Maggie Appleton tackled these challenges in one of her blog post’s entitled “The Dark Forest and Generative AI.”

Humans who want to engage in informal, unoptimized, personal interactions have to hide in closed spaces like invite-only Slack channels, Discord groups, email newsletters, small-scale blogs, and digital gardens . Or make themselves illegible and algorithmically incoherent in public venues.

The new challenge isn’t generating content — it’s proving that you’re human.

Fortunately, we humans evolved a whole bag of tricks to tell if something is a predator or not in the forest. Now we have to apply them online. Appleton suggests a few techniques in her post:

Triangulate – verify information from multiple sources (e.g. the SIFT strategy)
Be original – introduce new ideas (AI can only share what’s come before)
Be creative – use language quirks that AI wouldn’t use

In the future I expect we’ll see more institutional verification, similar to what LinkedIn has been rolling out for profiles. In LinkedIn’s case they are using a mix of ID verification (drivers license, passport, etc) to verify people and email verification to confirm companies.

Back to IRL as the norm?

If there’s something to be optimistic about, I suspect it will be the re-emergence of in-person value. Before the pandemic we were already seeing an uptick in “digital essentialism” as people got tired. We were then thrown even more into the online realm with the pandemic, and now we’re seeing more and more misinformation, astroturfing, and other deceptive practices online. I suspect more and more of us will be looking for connection outside the old electronic waterholes of Facebook, Instagram, etc.

I, personally, look forward to a slower, less online world if that’s indeed the future.

The myth of the average user

2024-12-31T00:00:00-08:00

This particular bit of history will live forever in my head.

In the late 1940s, the U.S. Air Force faced a deadly crisis: their pilots were crashing at an alarming rate, with 17 crashes in a single day at its peak. The military knew something was terribly wrong, but the cause eluded them.

Enter Lieutenant Gilbert Daniels, who conducted a groundbreaking study of 4,063 pilots. His discovery was shocking: when measuring ten critical body dimensions used for cockpit design, not a single pilot fell within the average range across all measurements. Not one.

This is the “flaw of averages” – the mathematical reality that designing for the average means designing for no one. The average user, like the average pilot, is a statistical ghost.

The Air Force’s solution revolutionized aviation: they abandoned the myth of the average pilot and instead created adjustable equipment. Cockpits with customizable seats, moveable control panels, and adaptable displays became the new standard – a design philosophy that saved countless lives.

This lesson extends far beyond aviation. While I always knew that averages could be misleading (after all, a single outlier can dramatically skew results), I never realized just how fundamentally flawed the concept of “average” could be.

The truth is simple: none of your users are average. Each person who interacts with your product brings their own unique needs, preferences, and ways of working. The key to exceptional design isn’t creating the perfect solution for an imaginary average user – it’s building flexibility into your core experience.

When designing software, you can (and should) have strong opinions about optimal workflows. But you should also embrace edge cases – whether it’s the power user who needs advanced features or the newcomer who needs a simplified interface – to create solutions that work for everyone.

Want to dive deeper into this fascinating story? Check out the original article in the Toronto Star for more details.

Weighing in on AI hype and risk

2024-12-10T00:00:00-08:00

Casey Newton wrote a piece last Thursday titled “The phony comforts of AI skepticism” — and wow did people have some thoughts about it:

Gary Marcus responded against the mischaracterization of his position
Edward Ongweso had quite a few more things to say
Casey Newton responded while basically doubling down on his argument
Dave Karpf waded in with his perspective and a recap of the debate

I’m sure there’s more out there but you get the idea. I almost didn’t write something myself, but one part of this conversation still feels like it’s missing to me. So let’s take a brief look at Newton’s argument before diving in.

Newton’s argument in a nutshell

To briefly summarize, the core thrust of Newton’s piece is that the entire range of AI discussion boils down to two groups: critics external to firms and organizations directly working on or studying AI who believe “AI is fake and sucks” and internal critics building AI who understand “AI is real and dangerous” given current and future capabilities. Newton aligns himself with the latter and suggests that the former camp are not only incapable of recognizing genuine innovations made in this field, but risk leaving us blind to threats enabled by those advances.

It’s a widely reductive argument and Marcus and Ongweso do a great job of breaking down the issues with it, and in particular the straw man Newton builds for himself to attack. I’m not going to wade in there, but I recommend reading their posts for context.

I want to talk about how smart journalists like Newton can accidentally (or intentionally) fall for the hype, and in the process fail to correctly frame the conversation for their readers. And I want to be clear up front: I think this was a huge miss.

A false dichotomy

My particular issue with Newton’s article is about the placement of what I’ll call skepticism (“AI is fake and sucks”) and hype (“AI is real and dangerous”) as polar opposites on a spectrum. It’s so wildly off I’m surprised Newton chose to defend it. As many people noted in comments on Mastodon and Bluesky, the skeptics Newton is attacking are more likely to fall into the “AI is real and dangerous and is also fake and sucks” category.

Understanding how current generative AI models, and large language models (LLMs) in particular, fail to deliver on their promise usually means you also understand how dangerous these models are now, and will be in the future. Those shortcomings are especially dangerous when they are released to a public that doesn’t understand what those shortcomings are, and into a media environment that is still grappling with the ramifications of social media.

Sorting out risk from hype

My bigger issue is that Newton seems to fall for the hype from the people building and most likely to benefit from advances in AI. And make no mistake, making unsubstantiated claims about the future dangers of AI is a way of creating hype around the technology. It’s probably the oldest form of hype in computer science – we’ve been talking about imagined AI risks since at least the mid-19th century.

The problem here is that hypothetical risks are treated the same as actual risks. We know that the current GenAI models are accelerants to the issues of propaganda and misinformation that were already widely present on social media and other communication channels before ChatGPT was released. GenAI models are also wrong quite often, despite attempts to improve them, leading to a new form of misinformation when users aren’t appropriately skeptical of the responses they receive. And that doesn’t get into whether LLMs are even a viable path to true general intelligence or not.

We should be talking about emerging risks, but we need a lot more grounding in the conversation from journalists like Newton. And we should differentiate these as hypothetical risks, and they should be treated with more skepticism, especially when they come from the people most likely to benefit from them.

Final thoughts

As Marcus outlines at the start his essay, Newton does get a lot right, including that we should be preparing now for AI to get more dangerous. And we should be documenting the different attitudes that are emerging around AI. I agree with all this.

But we need the media to do a better job of framing the emerging discussion and attitudes towards AI without serving as hype for the individuals and firms building and benefitting from these models.

How to package new product features

2024-10-19T00:00:00-07:00

When your company develops new innovations, a key question is: how should you package those features within your current product tiers? This decision can significantly impact customer perception of value and the ease of selling it.

There are two main factors to consider:

Perceived value – How much will customers see this innovation as something that enhances their experience or solves a problem?
Target customer size – How many of your customers would actually benefit from it?

Here’s an easy framework to visualize your options:

1. New Product or Tier

If the new capability stretches beyond the value of your existing tiers, or it could shift the positioning of your entire product, it may be better to create a new tier or even an entirely new product. This will need more effort in field enablement and communication, but it also opens the door to greater potential revenue.

2. Add it to an Existing Tier

This is the right call if the innovation fits seamlessly with the current messaging of your product. Adding it to an existing tier can make the sales process easier because you’re building on something customers already understand.

3. Make it an Add-on

Sometimes, the innovation only appeals to a small segment of your customer base. In this case, packaging it as an add-on is a good move. This way, it doesn’t disrupt your core product offering, but customers who need that extra functionality can still get it.

4. Do Nothing/Kill the Initiative

And sometimes, the best option is to not move forward at all. If the perceived value is low and only a small percentage of your customers would care about it, it might be better to shelve the idea and try something else.

Working with multiple GitHub accounts and SSH keys

2024-05-09T00:00:00-07:00

I have multiple GitHub accounts – one for work, one for demos, and one for personal projects. Each has a unique email address, password, and 2FA associated with it. They also each have a unique SSH key. In fact, the SSH keys are all saved in different 1Password accounts (personal, demo, and work).

In some cases I perform the development on the same device, like when I’m building a demo on my work device. In that case I need to make sure that I’m using the correct GitHub account and SSH key.

I use 1Password as my SSH agent because it keeps the private keys off my device, plus it makes authorizing SSH connections a breeze. I can authenticate a connection using Touch ID, so just a fingerprint touch on my keyboard and then I’m off to my next task.

Fortunately, this only takes a few minutes to setup!

Organize your local directory

All my repositories are saved under a GitHub folder and then I use directories to organize my projects by account. Although I prefer to keep personal and work separate, you could configure all three accounts for a single device like in the example below:

~/github
├── /demo
├── /personal
└── /work

This will make it very easy to configure which profile and SSH key to use in the following steps.

Set your global gitconfig file

In this example, I’m setting my personal Git configuration as the global default. Using [includeIf] I specify a different .gitconfig file for the demo and work directories.

[user]
  name = <github_personal_name>
  email = <github_personal_email>
  signingkey = <your_ssh_key>

[gpg]
  format = ssh

[gpg "ssh"]
  program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"

[commit]
  gpgsign = true

[includeIf "gitdir:~/github/demo"]
  path = ~/github/demo/.gitconfig

[includeIf "gitdir:~/github/work"]
  path = ~/github/work/.gitconfig

Create gitconfig files for each directory

Next I’ll create .gitconfig files and save them in the demo and work directories. I’ll use a similar template, but this time I’ll provide the GitHub name, email, and public signing key for my demo and work accounts.

[user]
  name = <github_work_name>
  email = <github_work_email>
  signingkey = <your_ssh_key>

[gpg]
  format = ssh

[gpg "ssh"]
  program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"

[commit]
  gpgsign = true

Configure the SSH agent

In order to call the correct SSH keys, I’ll need to update the SSH agent config file located at ~/.ssh/config.

I start by setting the 1Password SSH agent as the default for all hosts. Then I create custom hosts for each account, in this case Demo, Personal, and Work.

Next, I downloaded the public keys from 1Password for my demo, personal, and work accounts. I renamed each file (for example, demo_git.pub) and saved the all to my ~/.ssh/ folder.

# By default, use the 1Password SSH agent for all hosts
Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

# Demo GitHub
Host gh-demo
    HostName github.com
    User git
    IdentityFile ~/.ssh/demo_git.pub
    IdentitiesOnly yes

# Personal GitHub
Host gh-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/personal_git.pub
    IdentitiesOnly yes

# Work GitHub
Host gh-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/work_git.pub
    IdentitiesOnly yes

Reset your local repositories

Finally, I’ll need to reset each individual repository so it uses one of the hosts specified above. This will make sure it uses the correct SSH key to authenticate with GitHub and when pushing Git commits.

git remote set-url origin <host>:<organization>/<repository>.git

Finally, run git remote -v to confirm that Git is using the correct remote repository. You can run git fetch to confirm that 1Password offers up the correct SSH key for authentication.

Resources

Configure Multiple Git Signing Setups (1Password)
Use Multiple GitHub Accounts (1Password)
Adding a New SSH Key to Your GitHub Account (GitHub)
Register a Public SSH Key with GitHub (1Password)
Testing Your SSH Connection (GitHub)
Switching Remote URLs from HTTPS to SSH (GitHub)
Optimize Your Git Setup: Strategies for Handling Multiple GitHub Accounts (Dev.to)

Thoughts on information fidelity and transmission

2023-08-25T00:00:00-07:00

There is a useful axiom to keep in mind whenever you are crafting a message for someone else, whether writing a book, filming a video, or drafting an email.

Simple ideas travel farther than complex ones

Most of us intuitively understand this. But sometimes we forget as we get into the details of whatever we are doing. That’s why I like to keep the idea of fidelity vs transmission in mind.

A book has hi-fidelity, but low transmission. You can read an author’s ideas in depth. Everything they wanted to tell you is there. But the full message — the text of the entire book itself — will practically never be remembered or transmitted, in detail, to the recipient. They may highlight the text, take notes, and summarize the text. But the full message will be lost.

In contrast, a social media post has lo-fidelity, but high transmission. The full idea is almost invariably reduced to its essential elements. Details are left out. Things become black and white. But the recipient might be able to remember the entire message, so it has high transmission.

This is why slogans are so powerful. They are easy to remember, and collect associations with other information you might have received or interacted with about a brand, politician, or idea. But they don’t have to communicate the whole thing – the recipient fills in the rest.

Why does this matter?

There is an inherent tension between fidelity and transmission in all communication. Too much information, and your audience won’t remember what you needed them to know. Too little, and the message becomes banal, or simply worthless.

There is an ethical element to navigate as well, especially when reporting or documenting someone else’s experience. Storytelling is reductive: it removes and flattens details in favor of creating an understandable narrative. The details you include or leave out will shape an audience’s understanding of the message you are communicating.

What does this look like in practice?

Practically, this is why most messaging frameworks provide multiple tiers:

Pillars — Simple, two or three word phrases
Key Message — Short, memorable statements
Proof Points — supporting statements, benefits, or other evidence

From here, you can expand into even higher fidelity forms like blog, videos, white papers, or books that expand and build on the summary provided by the messaging framework.

Closing Thoughts

We see the impact of this all the time. Stories go viral based on a bit of sensational news. But as the details come out, the original story turns out to be false. Bias and hate travels farther and faster than the nuance of compromise and collaboration.

As a writer, marketer, or anyone who works with words, how do you balance fidelity and transmission in your work?

Writing for technical audiences

2023-05-06T00:00:00-07:00

Whether you are marketing to software developers, scientists, academic audiences, or other specialized industries, writing is a tool that can serve you well.

But writing for technical audiences is a unique skill that requires a different set of techniques than copywriting for a consumer marketing campaign. You need not only an in-depth understanding of the subject but also the ability to convey complex information clearly and concisely.

The following tips can help you to communicate your ideas more effectively.

Know your audience

One of the tricky aspects of writing for technical audiences is knowing when to simplify something, and when to assume a level of advanced knowledge. Nothing drives developers, scientists, and other technical audiences away faster than overly simplified, 101-level writing. Occasionally, you do need 101-level content! But know what level of information your audience should already know.

For example, I often write about API technologies. In 101-level content, I might define that the acronym API stands for an application programming interface. But if I start an article for a technical audience by introducing “what is an API” and defining the acronym, they are likely to quit reading and look for a resource that is more aligned with their knowledge level.

Use clear language

When writing technical documents, it can be tempting to use complex technical jargon and terminology. However, this can often make your writing more difficult to understand, especially for those who are not familiar with the subject.

To avoid confusion, it is best to use simple, clear language that is easy to understand. This means avoiding overly technical terms and breaking down complex concepts into more digestible pieces. You should also summarize key ideas in bullet points, which can help reinforce your ideas and improve retention.

One of the most important first lessons I learned was to avoid adverbs whenever possible, especially in headlines. Adverbs typically make writing “feel like marketing” because they make broad claims (for example, “quickly, effortlessly, rapidly, always”).

Provide evidence

In technical writing, you should avoid making sweeping statements or generalizations. It is important to back up any claims you make with evidence. This could be in the form of data, statistics, or references to existing research. By providing evidence to support your arguments, you can add credibility to your writing and show that your ideas are based on solid research and analysis.

A brief word of caution: most technical audiences know what is a valuable resource, and what is marketing evidence. Use authoritative sources whenever possible, or commission relatively neutral third parties to conduct research on your behalf.

Give concrete examples

Whenever possible, show rather than tell your audience how your product works. It’s one thing to claim that something is easier. But it’s more impactful to show it in action. Rather than relying on abstract concepts or hypothetical scenarios, try to use real-world examples to illustrate your points. For example, if you are writing a user manual for a software application, you could include screenshots or step-by-step instructions to help users understand how to use the software.

Use visuals

Visual aids can be extremely helpful in technical writing, as they can help to clarify complex concepts and make your writing more engaging. This could include diagrams, charts, graphs, or illustrations. Visuals can be particularly effective when you are trying to explain a complex process or system, as they can provide a clear, easy-to-follow representation of the subject.

Incorporate storytelling

While technical writing is often associated with dry language, incorporating storytelling can make your writing more engaging and accessible. This could involve using anecdotes, case studies, or narratives to illustrate your points. Techniques like metaphors, extended analogies, and other techniques can be valuable ways to explain complex topics or frame a concept in a new way. By using storytelling, you can help your readers understand the subject on a deeper level.

Summary

Technical writing is an essential skill for anyone working in a complex field, or marketing to experts. By following these tips, you can ensure that your technical writing is clear, concise, and easy to understand, helping you to communicate your ideas more effectively to your intended audience.

A few parting questions to consider:

Are there any examples of technical writing that you particularly admire What made it stand out, and what lessons can be learned from its approach to technical writing?
What are some strategies for using visuals effectively in technical writing
Are there any tips you would add to the list above?

Additional Resources

How to Get Started with Technical Writing – tips for building your technical writing skills and portfolio
A Software Developer’s Guide to Technical Writing – useful tips for anyone interested in writing for software developers
Hemingway Editor – an excellent resource for sharpening your writing and removing those pesky adverbs

Thoughts on open-ended writing

2023-03-03T00:00:00-08:00

Writing online, especially for a blog, can feel difficult. Especially for a (recovering) social media and content marketer like myself. Yes, it’s easy to make a blog. It seems like there are constantly new tools popping up promising to help you blog, build a newsletter, or post on social media.

But writing is a different matter. Today it seems like blogging is focused on producing capital “C” Content for consumption. Everything becomes an “ultimate guide to X,” even if you try to use slightly more tasteful titles. With the arrival of Chat-GPT and other AI tools, the world is faced with even more bland and repetitive capital “C” content as the “dark forest” of the web expands, to borrow a term from Yancey Strickler.

This isn’t inspiring. And it’s rarely enjoyable to write these types of articles.

Digital Gardening and Small b Blogging

When I started writing on this website (again), I wanted to treat it more like a digital garden. I’d like to expand my thoughts on digital gardening sometime, but I think Maggie Appleton has the best working definition for now:

“A garden is a collection of evolving ideas that aren’t strictly organised by their publication date. They’re inherently exploratory – notes are linked through contextual associations. They aren’t refined or complete - notes are published as half-finished thoughts that will grow and evolve over time. They’re less rigid, less performative, and less perfect than the personal websites we’re used to seeing.”

This approach resonates with me. Mainly because producing exhaustive articles is, well, exhausting. This definition of the digital garden is similar to the concept of “small b blogging” introduced by Tom Critchlow:

“Small b blogging is learning to write and think with the network. Small b blogging is writing content designed for small deliberate audiences and showing it to them. Small b blogging is deliberately chasing interesting ideas over pageviews and scale. An attempt at genuine connection vs the gloss and polish and mass market of most content marketing.”

I recently read another note by Tom Critchlow that was the direct inspiration for this line of thinking, entitled “Writing, Riffs, and Relationships.” There are lots of good concepts in the article, but the idea of making writing small stood out to me. In particular

“People’s first instinct with content is to try and make it polished and closed. To be useful by solving something or creating the ultimate guide to something. Those pieces of content can be good - but they’re very hard to write, and even harder to write well! Instead I prefer to take a more inquisitive and open-ended approach….”

And then:

“Closed writing is boring writing. If you’ve fully explored and put to bed the topic you’re writing about then there’s very little left for someone to react to. “Nice post” someone might say.

But if you deliberately leave some rough edges, some threads that the reader can pull on, then you’re inviting the reader into the conversation. You’re saying (possibly explicitly!) - “Hey, what are your thoughts on this topic? How do you think about it?”

Critchlow goes on to recommend ending a blog post or “riff” with more questions that encourage you (and your audience) to explore other topics. Altogether, this made me think about the difference between open-ended and closed writing and how they are different modes of writing altogether.

A Brief Definition of Open-Ended Writing

Open-ended writing seeks to connect ideas and identify new pathways of inquiry. It explores a topic by connecting sources and identifying tensions, conflicts, or missing information. Open-ended writing invites conversation and debate.

In practice, open-ended writing is defined by three basic activities: free writing, summarizing, and questioning:

Free writing introduces sources, ideas, and questions and starts to connect them together.
Summarizing organizes the information into a statement of what is known so far and what has been covered.
Questioning identifies tensions and gaps that could be explored further in the future or invites areas of conversation.

Some Spring Cleaning

I started this blog to write small, informal blog posts. So far I’ve fallen back into the trap of writing “articles” that don’t really encourage conversation or provide new threads to pull on. While it’s not critical for doing the actual writing, I decided to re-classify my digital garden to encourage myself to focus more on riffs and notes.

Previously, I had two categories: Notes and Essays. Notes were supposed to be objective and focused on single topics; essays would pull together multiple notes to present a specific point of view. Obviously, neither category encouraged exploratory writing. I generally wrote less and focused on polishing my notes, which were supposed to be the rough form of writing. I seldom got around to writing essays.

I now have my digital garden organized into three categories:

Notes– Open-ended, exploratory riffs that connect 2-3 ideas or sources together. These are the heart of the digital garden.
Articles – Closed writing that thoroughly explores a single topic from a mostly objective point of view.
Essays – Utilizes either open-ended or closed writing to explore a single subject from a personal point of view.

How do you practice open-ended writing?

This particular post might be my first true note. It’s not meant to be comprehensive and it’s mostly my attempt to work out (in public) an approach to open-ended writing.

What do you find hard or challenging about writing?
Does changing the purpose to open-ended writing encourage you to write more? Or does it scare you?
Do you use a public platform or a private one? Is one better than the other, or are they just different?

Pocket guide to privacy-first email newsletter software

2023-02-09T00:00:00-08:00

When I first started to look for privacy-first email newsletter options back in 2019, there just weren’t many options. There were great privacy-first website analytics tools like Fathom Analytics, but nothing for email. Nearly every provider required tracking pixels by default.

I want to briefly acknowledge that there are some legitimate reasons why email newsletter software providers might require pixels. Tracking pixels are one way to evaluate a sender’s reputation and ensure overall deliverability for everyone using their platform. Higher open and click rates indicate that a list is engaged. The reverse could indicate that an account is sending spam emails.

The problem is that tracking pixels collect far too much information, including exact location information from each recipient. Most of us understandably don’t want senders to know where we read an email, how many times we read that email, what links we clicked, and how many times we clicked each link.

There are, of course, other ways to evaluate list engagement. Unsubscribes and spam reports are a clear signal – and they are the indicators that matter most. As a sender, you can evaluate email engagement by website traffic, list growth, unsubscribes, spam reports, and other methods.

The good news is that over the past year or two many major email newsletter providers have started to let you turn off email trackers (e.g. MailChimp, but with limitations). Other providers still do not (e.g. ConvertKit).

I wanted a provider that offered a privacy-first by default platform. So I compiled a list and I’m sharing it here. My criteria for inclusion in this list were simple:

Open and click tracking are turned off by default
Does not use Google ReCaptcha on the subscription form
Does not have third-party trackers (e.g. Google Analytics) on their website

Below is a list of the email newsletter services that met the criteria, as well as their lowest price point as of February 9, 2023:

Company	Tracking	HQ Location	Cheapest Plan
Buttondown	Off by default	US	Free up to 100 subscribers
SendStack	None	EU	Free up to 100 subscribers
MailCoach	Off by default	EU	$9.99

Buttondown

Buttondown is a minimalist tool for writing and producing email newsletters. Based in the United States, it is run as an indie software business. Buttondown gets a lot of things right, like privacy-first by default (you can, however, opt-in to tracking if you want), the ability to write in markdown, RSS-to-Email tools so you can run your own version of Substack, and a first-party API that is included in the free plan for the hackers among us.

SendStack

SendStack is one of the newest tools and was released by a team based in the European Union (Germany, specifically). It has fewer features than Buttondown but a much friendlier user interface. They also make their first-party API available to free plans, which is a great feature for developers or anyone wanting to build their own first-party email newsletter subscription form. SendStack takes a much harder line on automation, however, so there is no RSS-to-Email function or other automation tools.

MailCoach

MailCoach offers both a hosted and a cloud-based solution. Interestingly, they also support transactional email. Like the other platforms here they offer a streamlined interface. But unlike Buttondown and SendStack, automation and transactional email are treated as important features. This is a good solution if you need more than just a newsletter, and would be a great option for agencies, businesses, or anyone building more complex email workflows.

Conclusion

I have personally used Buttondown and SendStack, but I haven’t tried MailCoach yet. This isn’t an endorsement of any particular service. You should try them out and see what works best for you. I also recommend this article comparing pricing models for privacy-first email newsletter services if you are considering one of these platforms.

But, if you’ve been looking for a private alternative to Mailchimp and similar services, you now have a handful to choose from. I’m looking forward to seeing this space grow as more creators and businesses start to adopt privacy-first marketing practices in the future.

Tools I'm using right now

2022-08-30T00:00:00-07:00

I’m always curious what tools people use in their work, so I thought it would compile a list of the tools I use for writing and productivity.

With that being said, use what you’re comfortable using or already know how to use. Outcomes are the most important; whatever tools you pick should help you get to the outcomes you want.

But there is a reason why we find tools fascinating. Tools can influence those outcomes, sometimes in a significant way! At least Abraham Lincoln thought so:

If I only had an hour to chop down a tree, I would spend the first 45 minutes sharpening my axe.

So with that introduction in mind, here’s what I’m using today. Hope you enjoy it!

Personal Productivity

Proton Mail: End-to-end enccrypted email for privacy and security

Things: Personal task management

Business Management

Google Workspace: Custom email domain and a business phone number

Wave: Free accounting for small businessess

Knowledge Management

Obsidian: Notes stored in markdown and synced with end-to-end encryption

Readwise: One app for feeds, reading, and highlighting

Marketing

Buffer: For scheduling social media posts

Buttondown: Privacy-first email newsletter software

Fathom Analytics: For privacy-first website analytics

Web Design

Jekyll: Static site generator

Namecheap: For buying domains

Netlify: For simply, static website hosting

Tailwind CSS: Utility-first CSS framework for designing websites

Visual Studio Code: Open-source code editing app

Writing

Copy AI: Side kick for brainstorming and copywriting

Ulysses: Markdown writing app

Build an email subscription form with Netlify Functions

2022-08-28T00:00:00-07:00

I enjoy the process of building and maintaining my own personal website. It’s a great way to experiment with different technologies, and have fun learning new tools and concepts along the way.

This time, I wanted to learn how to use serverless functions. There are a lot of great resources out there already. But I had trouble finding a guide that adequately addressed my use case: a humble email subscription form.

This tutorial is strongly inspired by an excellent guide created by Matthew Ström. I’ve added solutions for some of the problems I encountered while following his guide, but Matthew deserves the credit.

After going through all the work to build my personal website, the last thing I wanted to do was slap a pre-designed newsletter subscription form on it.

I wanted the flexibility to design my own custom forms for a few reasons:

Better design: Email marketing providers offer great default forms, but they never perfectly match a site’s design
Better Performance: External email forms require additional calls for CSS and Javascript, and they sometimes get blocked by privacy settings
Better privacy: Hosted email forms can collect additional information about users, like their IP address

I set out a few rules for this challenge:

It should work without extra JavaScript or AJAX
It must use Netlify functions
It shouldn’t need external dependencies

The Team: Jekyll, Netlify, and ConvertKit

My website is built using a static site generator called Jekyll. It allows me to build my own templates and components, so I’ll use it to build my email form. I also used Tailwind CSS Forms Plugin to simplify the design process.

I use a service called Netlify to deploy my website. It’s key for this project, because it complies the static assets built by Jekyll and runs the serverless function to send emails to my email list provider.

Finally, I’m using ConvertKit as my email list provider. I’ve also included information on how to use Buttondown and SendStack in this tutorial, but the basic principles of the function should apply to any other email providers that offers an API.

Ok, let’s get started!

Create the serverless function

You need to follow three basic steps to create a Netlify function:

Add API tokens to Netlify as environment variables via the admin interface
Tells Netlify where to look for your functions using the netlify.toml file 3. Write the function in a Javascript file in your project
Write the function as a Javascript file in your project

To start, let’s save the API token from our email service as an environment variable. Environment variables are useful to hold information that I don’t want to make public, like this API key. You can add an environment variable using the Netlify admin interface under your build and deploy settings.

Next, specify where Netlify should look for your functions. Edit your netlify.toml to specify the functions directory. It might look something like this:

[build]
   base = "."

[functions]
   directory = "netlify/functions/"

Create a function file in the directory you specified above. If you used the default functions directory, you should save your function at YOUR_BASE_DIRECTORY/netlify/functions.

Next, you’ll need to give your function a name. For example, to create a function with an endpoint name of hello-world, save the function in one of these locations:

netlify/functions/hello-world.js
netlify/functions/hello-world/hello-world.js
netlify/functions/hello-world/index.js

For this tutorial, I’m going to use the submission-created event trigger. Netlify will run my function every time a form is submitted. To do that, I’m going to name my function submission-created.js.

Now you’re ready to start writing the function. Start by importing the API key you created earlier as an environment variable:

const { EMAIL_TOKEN } = process.env

On line 2, I add a small library called node-fetch. This allows me to use Javascript’s Fetch API, which is how we’ll format an API POST request to send data to our email service.

import fetch from 'node-fetch';

NOTE: When I was writing this post, many of the tutorials available used the require method to import the Fetch API which resulted in errors when I tried to deploy the function. Make sure you use the method I described above. If you upgrade to node-fetch v3, you’ll also need to update either your netlify.toml file or package.json to use ESM.

[functions]
   node_bundler = "esbuild"

You can find more information about how to make a fetch request using node-fetch v3 in an excellent guide by Tatyana Novell on the Netlify blog.

Next create a synchronous function on line 4. The exports.handler value is where Netlify expects to find the function, so I define it there. The basic syntax to create the function is provided below:

exports.handler = async function (event, context) {
  // your server-side functionality
};

Next retrieve the email from the event value using JSON.parse:

const email = JSON.parse(event.body).payload.email

Then log the data in the console for debugging:

console.log(`Received a submission: ${email}`)

After retrieving the email address from the event value using JSON.parse, I’m ready to send it off my email marketing providers. I’ll use the node-fetch library I imported earlier to form the POST request.

I’ve outlined code examples for a few services below, but make sure you consult the API documentation from your email provider to make sure the API request is properly format.

ConvertKit Subscription Form

Using ConvertKit as an example, send a POST request to https://api.convertkit.com/v3/forms/<YOUR_FORM_ID/subscribe.

To find the form ID, navigate to Grow > Landing Pages & Forms, select the form you want to use, and copy the ID number from the url:

https://app.convertkit.com/forms/designers/<YOUR_FORM_ID>/edit

The body of the POST request contains the email token and the email address from the form submission:

const response = await fetch( 'https://api.convertkit.com/v3/forms/<YOUR_FORM_ID/subscribe', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
	},
	body: JSON.stringify({ 
		api_key: EMAIL_TOKEN,
		email: email
	}),
});

Buttondown Subscription Form

Buttondown’s API sends the authorization in the headers rather than the body, so you’ll need to adapt the code slightly:

const response = await fetch( 'https://api.buttondown.email/v1/subscribers', {
	method: 'POST',
	headers: {
		Authorization: `Token ${EMAIL_TOKEN}`,
		'Content-Type': 'application/json',
	},
	body: JSON.stringify({ email }),
});

SendStack Subscription Form

SendStack is a new privacy-first email service. Unlike Buttondown and ConvertKit, they offer API access on their free plan. There is currently a waiting list, but if you have access, you can try it out using the code below.

Add the email token to the headers and the email address to the body of the POST request:

const response = await fetch( 'https://getsendstack.com/api/subscribers', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${EMAIL_TOKEN}`,
		'Content-Type': 'application/json',
	},
	body: JSON.stringify({ email }),
});

Then capture and log the response from the email service. We do this to diagnose any issues that happened. Netlify makes it easy to check your function’s logs, so use console.log often!

let responseText = await response.text();
console.log('Response:', responseText);

Finally, redirect the form to a confirmation page that tells subscribers to check their emails to confirm their subscription. Use a simple return to redirect the browser to the new page:

return {
	statusCode: 302,
	headers: {
    	'Location': '/confirmation/,
	},
}

You can find the completed function below. In this case I used ConvertKit:

const { EMAIL_TOKEN } = process.env;
import fetch from 'node-fetch';

exports.handler = async (event, context) => {
    const email = JSON.parse(event.body).payload.email
    console.log(`Received a submission: ${email}`)

    const response = await fetch (
        'https://api.convertkit.com/v3/forms/{YOUR_FORM-ID}/subscribe', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({ 
                api_key: EMAIL_TOKEN,
                email: email
             }),
        }
    );
    let responseText = await response.text();
    console.log('response:', responseText);
    return {
        statusCode: 302,
        headers: {
            'Location': '/confirmation/',
        },
    }
}

Create the email subscription form

Now that you’ve built the function, let’s call it from the email subscription form. The HTML for the email subscription form is very minimal.

All you need to do is call the function using the form action:

<form name="newsletter" method="POST" action="/.netlify/functions/subscribe-email">
	<label for="email">Your Email Address</label>
	<input type="email" name="email" placeholder=Email Address"/>
	<button type="submit">Subscribe</button>
</form>

Make sure you specific input name (“email”) and make sure it matches the information you parse from the event value using JSON.parse.

If you used the submission-created trigger for your function like I did, you’ll need to change the <form> field slightly by adding data-netlify="true" to tell Netlify to process this form:

<form name="newsletter" method="POST" data-netlify="true">
  <label for="email">Your Email Address</label>
  <input type="email" name="email" placeholder=Email Address"/>
  <button type="submit">Subscribe</button>
</form>

Deploy the function

Now that I’ve written my function, configured my netlify.toml file, and added my environment variables, everything is ready to go. Deploying is painless: just set up Netlify’s GitHub integration, and your function will be deployed when your project is pushed.

Conclusion

It took less than 50 lines of code to create my own email subscription form including custom HTML and a serverless function to add new emails to my list. I wrote it all in HTML, CSS, and JavaScript, and everything is served from my domain. Plus, my website visitors get a nice experience whether they have JavaScript enabled or not, and it will still serve even if they have advanced privacy protection enabled.

Just start

2022-06-28T00:00:00-07:00

How long have you been working on a project with nothing to show?

I am an expert procrastinator. I spent three years building, tearing down, and restarting this blog. The colors were never right, I didn’t like the font, I needed just one more feature to be ready.

Finally, I decided to slim down to just what I need to write. The rest could come later. For now It’s minimal, but it’s all I needed to start.

Today you can publish your writing in less than five minutes. Start with tools like:

The list is endless. So what are you waiting for?

Start writing
Get feedback
Refine your work
Try again

One of the biggest misconceptions about writing or creating anything is that you should start with a strategy: “I’m going to write about X for people interested in Y.”

But here’s the truth: you don’t need a plan to start.

Write about whatever interests you. You’ll eventually find what you enjoy writing about the most and what resonates most with your audience.

You just have to start.

Here are three formats to get started:

Today I learned how to…
Did you read or hear about X? Here’s my reaction…
Someone asked me about X, so here is the answer

Keep a notebook with all the questions people ask you for help with. Write up your answers and publish them.

Eventually you’ll hit your stride — and you’ll probably discover an idea you could never have found while planning your strategy, picking brand colors, and brainstorming topics for your blog.

Start today.

Why is storytelling important for B2B marketing?

2022-06-22T00:00:00-07:00

Storytelling has been a buzzword in consumer marketing (B2C) for nearly a decade. And for a good reason. We, as humans, can’t help but tell stories. They are a critical way to convey information and build common ground.

Storytelling in B2C Marketing

When I think about storytelling in marketing, emotional, high-production ads from companies like Apple, Coca-Cola, REI, and Starbucks come to mind.

You’ve probably seen examples, especially around the Super Bowl or other significant events. For instance, in this 2015 advertisement, Apple uses Robin Williams’ speech from Dead Poets Society to sell the iPad Air.

I may not want to run out and buy an iPad right after watching this, but I do remember the ad. And I feel inspired to create something. That feeling is now associated with Apple and their products. The Apple advertisement is an excellent example of why B2C marketers rely on storytelling to build customer connections and trust.

Why Storytelling Matters for B2B Marketing

For a long time, B2B marketing has held out as a place filled with dry white papers and ebooks waiting behind lead generation forms.

But storytelling is even more critical for B2B (enterprise) marketing.

Unlike most B2C products, in B2B marketing, you are selling to groups of people who need to make a decision together. These diverse groups of individuals have unique needs and problems that need to be solved. In many cases, you may sell to stakeholders whose problems you don’t directly solve (typically C-suite leadership).

The only way to win a deal with so many people is by first uniting everyone around a common cause that turns their problems into a set of shared obstacles to overcome.

A successful story must resonate with everyone in the buying process and establish a higher-level mission to solve together.

Successful B2B marketing starts with a strategic narrative — why your company exists and what you help solve. One of my favorite examples is Microsoft’s new mission under CEO Satya Nadella: to empower every person and every organization on the planet to achieve more.

Microsoft can apply a simple story to consumer products and business tools. It can reframe whatever Microsoft sells around helping customers achieve a shared goal. That could include better healthcare outcomes, increasing student achievement, or building inclusive workplaces.

Takeaway

To summarize, storytelling is an essential component of B2B marketing because it is a powerful tool for persuasion that can help align groups of buyers around a shared narrative. With the right story, you can inspire confidence and build trust with your customers.

Let me know what you think on Twitter and LinkedIn.

How to differentiate your product when you aren’t (really) different

2022-06-21T00:00:00-07:00

Product differentiation communicates the unique qualities of your brand or product to distinguish it from your competition.

But what if your product isn’t unique?

Today plenty of products go to market without unique features. In the early days of B2B software, it was common to have features that no one else had in the market. Differentiation was reasonably straightforward. You would identify the unique benefit your feature provided for customers and craft a positioning statement around it.

In today’s technology landscape, differentiation with features is rare — everyone has similar functionality.

For example, you probably own a smartphone. Maybe you even own an Apple iPhone like more than 50% of U.S. consumers. But can you tell me the difference between the screen resolution on your iPhone versus a Samsung Galaxy? Are they even different?

Your opinion of that question is likely influenced by brand differentiation more than the unique qualities of either phone. Do you know how many pixels are in a Retina display? Or how that’s different than the screen on a Samsung phone?

It’s easier than ever for competitors to copy your product. But does that mean you shouldn’t build a great product? Nope.

It just means that a great product is table stakes.

Companies that are beating their competitors have a great product and build a unique market position.

Here’s how you differentiate your product from the competition:

Target a niche market segment
Tell a differentiated story
Provide valuable education
Build a community around your vision
Cultivate a partner ecosystem
Amplify employee advocacy

Each takes time to build. But don’t get intimidated—that’s the point. Your competition cannot easily duplicate your work.

Let’s explore how you can differentiate your product even when your products don’t have any unique features.

Target a niche market segment

The first mistake many companies make is targeting too large a market. When you’re trying to please everyone, you please no one.

Success starts by narrowing in on a niche in the market that isn’t being served well by current solutions. If you’re familiar with Geoffrey Moore’s book Crossing the Chasm, you might recognize this approach by another name – “land and expand.”

You may have to niche down a few times to find the right fit in the market, progressively narrowing in on a smaller and smaller customer niche each time.

But wait, you might ask, don’t I want a bigger audience?

Eventually, maybe you will. But not when you are struggling to gain traction with your first customers. The more specific and targeted you can be with your positioning and messaging, the more your product will resonate with your customers.

I think ConvertKit is an excellent example of the niche-down approach. When Nathan Barry started the company, he targeted anyone who needed email marketing. As a result, he was up against heavyweights like MailChimp, ActiveCampaign, and others. And he was failing to gain traction.

Instead of giving up, he narrowed his market to target professional bloggers and worked to address their problems. He gradually expanded to other digital creators as he gained traction with bloggers. Today the business operates at over $100,000 monthly recurring revenue (MRR).

Check out Nathan Barry’s Twitter threadc for more about his journey building ConvertKit.

Tell a differentiated story

When trying to differentiate your business, the most crucial question is not “what makes our product better than others?” Instead, it’s “why should customers care?”

The most successful businesses don’t just sell products; they tell stories and motivate customers to buy into their vision. Instead of discussing what features make your product so great, talk about why it matters. Great stories are never about your products or services. They are about how people use your products and services to improve their lives.

If you are a B2B company, tell the story about how your customers use your products or services uniquely. If you are B2C, tell the story of how consumers use your products or services to improve their lives.

Whatever story you tell, ensure it provides a unique point of view on the market you are targeting. For example, how do you understand the market? What is your unique take on how to address challenges within your space?

Drift is an excellent example of how this can work in practice. They offer chatbots for customer service. But instead of focusing on automation, they invented a new category for their product named “conversational marketing.” They worked to build leadership within that term and created a stronghold in the market despite competition from other vendors in the space.

Check out this HubSpot blog post with examples of 10 companies that brilliantly differentiated themselves from the competition.

Provide valuable education

Educate your audience about the trends and challenges you see in the market, how they can solve their problems, and how to get the most value from your product to solve those challenges.

The key is to help your customers. Whatever you create (blog, video, ebook, podcast, etc.) should help your customers learn something new. You can even take this further and provide certification or verification that they have learned a specific skill. For example, how to use your product (Microsoft Azure Fundamentals) or a particular set of skills (HubSpot Inbound Marketing).

My favorite example of education is Buffer, especially in its early days as a company around 2012–2016. Their blog consistently published valuable content about social media strategy and tactics. Then they shared it via newsletter and social media.

Personally, Buffer’s blog was invaluable when I was starting a career as a social media manager. At that time, there were no college programs or classes for digital marketing. And there weren’t that many other people who had much experience yet either. Nevertheless, we were all learning on the job. Buffer filled a gap by breaking down trends from their data and offering actionable tips daily.

Build a community around your vision

You need to do more than publish content on your blog. It would be best if you found ways to connect with potential customers one-on-one to understand their problems and how you can help.

One of the best ways to do this is by building a community around your vision. Find where your audience interacts online or in person and gradually join the conversation. If you’re already creating valuable educational content, it should be easy to chime in as questions arise. Eventually, you’ll want your audience to buy in and start sharing your vision.

Remember that a community can be centralized (Slack, Discord, Facebook Groups) or decentralized (conversations and hashtags on social media).

Different companies take different approaches depending on what they want to accomplish. For example, Nike, REI, and Starbucks have massive audiences online. As a result, they can rely on social media to amplify their brand messages and drive conversation around their brands. (The REI OptOutside campaign is a great example – people opt-in and interact around it every year.)

Other brands rely on bringing people together in a centralized space. For example, developer communities often organize around Slack or Discord as a place to discuss problems and share ideas – the VueJS community is a great example.

Cultivate a partner ecosystem

In addition to building a network with your customers, you should try to recruit partners who share your vision or philosophy. There are three main ways that partners can help differentiate your product:

1) Provide value-added services Partners function as an extension of your organization. By partnering with other companies, you can offer added value to your customers by leveraging their expertise. For example, your partners could provide anything from training and support to custom development and integration services. By providing additional services, partners can help your customers realize the full value of their investment in your product.

2) Provide product extensions and integrations Partners can provide extensions to your core product, adding new functionality and features that complement what you build. Integrations help customers build seamless workflows that address their specific use cases.

3) Generate co-sell opportunities In addition to extending functionality through integrations, partners can generate new sales opportunities by selling your product and theirs together as a bundle. Selling together is especially effective when the two products are complementary rather than competitive (e.g., CRM + marketing automation).

Once you start noticing how common partnerships are in the market, it’s hard to stop seeing them everywhere. One recent example I came across recently as a business owner was a bank – Novo. They help small business owners get started with business checking accounts.

Novo has built a partner ecosystem that helps new business owners get started faster. They offer discounts and integrations with critical partners like Quickbooks for invoicing, Stripe for collecting payments, and HubSpot as a CRM. New customers get access to these additional perks. By building a partner ecosystem, Novo helps drive business for their partners and helps keep customers invested in using Novo as their bank of choice.

Amplify employee advocacy

You automatically extend your reach when your employees advocate for your brand through their social ecosystem.

But more importantly, you can increase trust.

Customers often look to your employees as the best source of information about your company and products. According to research from Edelman, 68% of consumers say they trust technical experts from a company over the CEO or marketing material.

So why do customers trust employees?

They know more about your company and your products than anyone else
They know what your product can do – and what it can’t do
They know your competition and category and how you fit in
And most importantly: they know what matters to your customers

To succeed, you must first build a culture of trust and sharing. Unfortunately, most companies try to buy some software, implement it, and then give up when employees are less than enthusiastic about it.

A winning example, however, is Refine Labs.

The entire company is active on LinkedIn, sharing insights and commenting on posts about demand generation. Their success isn’t the result of fancy tools — the company’s CEO, Chris Walker, built advocacy into the culture through his leadership, hiring, and coaching of the team. It’s part of their core identity.

The result? A differentiated brand

The strategies above take time and a dedication to implement. That’s why they are so successful. Unfortunately, most companies fail to sustain the needed work to build a differentiated product and brand.

So now that you better understand how to differentiate your product, it’s time for action! If your product has no unique features, you can use the strategies above to differentiate your product and company from the competition.

And if you do have some unique features? Well, don’t stop promoting those just yet! You can still use these strategies to show off what makes your company special.

Let me know what you think on Twitter and LinkedIn. Thanks for reading!

Networking tips for remote and hybrid work

2022-05-25T00:00:00-07:00

You’ve finally landed that dream job — and it’s going to involve some (or a lot) of remote work. Maybe it’s your first job, or maybe you just took a position with a new company. Or, like the rest of the world, you and your team have transitioned to working remotely during the pandemic.

Regardless of the reason, you are now tasked with building relationships with co-workers you rarely see in person.

I had to onboard remotely twice during the pandemic. It was a much more challenging experience than starting in person. The first weeks can feel lonely, and it takes time to build the visibility and trust you need to drive projects forward.

That said, I love working remotely. And I’ve learned a few things along the way.

Here’s how you can network effectively in an era of remote and hybrid work:

Polish your LinkedIn profile
Schedule virtual coffee meettings
Engage with professional communities
Share what your learn

Polish your LinkedIn profile

Your LinkedIn profile isn’t just for finding a job — it’s also your first impression when meeting and networking with colleagues at your new company.

When I worked in person, I rarely checked my colleagues’ LinkedIn profiles. And why would I? We could chat at our desks or run into each other in the office.

After onboarding remotely twice during the pandemic, I can say with certainty that your LinkedIn profile matters more than even your resume. It’s the first place people look to understand who you are and what you’re about.

I use LinkedIn before scheduling meetings with people I haven’t met yet, or during meetings when I encounter someone new, so I can quickly identify their role and what might be important to them.

Here are some tips on how to optimize your LinkedIn profile:

Write an engaging introduction section that explains your career path, professional interests, and scope of responsibilities
Update your profile regularly so that it reflects your current role at the company, key successes and projects, and relevant skills
Make a great first impression with your LinkedIn headshot — it doesn’t need to be fancy but make sure your face is clearly visible

If you’re looking for more tips, I suggest browsing this comprehensive LinkedIn profile writing guide from the team at Jobscan.

Schedule virtual coffee meetings

When you first join a company, schedule 1:1 meetings with various stakeholders. I treat these like informal coffee chats and use them as an opportunity to learn about what people are working on, what their priorities are, and how I might work with them on shared goals.

Be proactive about introductions – don’t wait for others to introduce themselves. You should focus on meeting with your peers just as much, or maybe more, than meeting with different leaders.

Your goal here is to make sure that people know who you are and what your role is at the company. This helps build relationships early on so that when there are opportunities for collaboration or mentorship later down the road, there will already be a foundation of trust between you and other members of your team.

Don’t be afraid to ask questions and share ideas! Starting a new role is an exciting time to learn. And most people enjoy being consulted as experts in their areas and are willing to share what they know.

Once you’ve established a relationship with someone, it’s important to keep up the communication even when you aren’t working together. Connect over Slack or Teams by sharing interesting articles or news, checking in on how they are doing, or chatting about shared interests.

One of the best things you can do is recognize when someone else is doing something great. Send an email thanking them for their work and letting them know how much you appreciate what they did — especially if it wasn’t necessarily part of their job description. If you’re announcing a major event to your team via Slack or Teams, make sure to tag and thank them in the post.

Engage with professional communities

The rise of professional communities on Slack, Teams, Discord, and other platforms has created many opportunities to connect with other professionals.

Find out where your colleagues hang out online and join their communities. Personally, I use the Product Marketing Alliance (PMA) Slack group as a way to read about product marketing topics, ask questions, and connect with other professionals by answering questions when I can.

Seek opportunities to attend or present at conferences. These are great opportunities to meet other professionals face-to-face and share experiences. They can even be a great way to network with your team or other people at your company if you can attend as a group.

Even though I worked as a content marketer and social media manager for several years, I’ve always been a bit shy when it comes to writing on my blog or using my social media profiles.

After starting two remote roles, I now recognize the importance of creating and sharing valuable content in a remote and hybrid work environment. It’s a way to build reputation and network within your organization just as much as it’s a way to network outside your company.

Be active on social media platforms like LinkedIn or Twitter. Or even better, start a blog, publish a newsletter, or create videos. The goal is to get your voice out in public and get your ideas in front of your co-workers regularly.

Sharing what you learn in public is a great way to build your reputation and connect with people who might share some of your interests. The more people see your name associated with valuable content, the more likely they are to trust you as an expert and reach out when they have questions or need advice from someone with your background.

At first, don’t spend time worrying about having a unique angle, beat, or perspective. Just start and tweak as you go. If you’re not sure what to write about, try one of these prompts to get started:

Today I learned how to…
My favorite tools for X are…
I was thinking about…

The last prompt is actually how this post started. I was thinking about how to better network while onboarding into my new role and decided to write this blog post as a way of teaching myself the best way to get started.

Be patient

Finally, be patient with yourself (and with others). Starting a new job is exciting, and you want to get going right away. Building new relationships takes time, and it’s going to feel lonely at first. If you work remotely, you will have to be ok leading your learning, networking, and career building.

On the flip side, it is also empowering. Remote and hybrid work environments offer greater flexibility, work-life balance, and autonomy. I love taking a few minutes to grab a cup of coffee from my kitchen, pet my rabbits, and take in the view of my neighborhood rather than the concrete downtown streets before heading back to work.

Please let me know what you think on Twitter or LinkedIn. Thanks for reading!

How to style an Atom feed with XSLT

2022-01-24T00:00:00-08:00

Maybe it’s nostalgia for the early web, but I love web feeds as a tool for following and reading content. Feeds are privacy-first and put the reader in control: you can opt out any time, choose your tool for reading, and organize them in any way you want.

But the UX experience is terrible.

Web feeds are meant to be machine-readable, so most users follow a link to an RSS or Atom feed and end up looking at something like this:

This doesn’t have to be the case. RSS and Atom feeds can be human-readable with a little extra work. Here’s an example from my website. It’s simple and clean and provides some essential instructions on how to get started:

Let’s explore how to implement this with Atom and an XSLT stylesheet.

Why Atom, and not RSS?

Great question, and one I don’t intend to answer fully here given the vast amounts of writing on this topic already. In short, Atom is a better format.

Specifically, I wanted the following:

Support for a full content payload in the feed
Wide support across feed readers
Extensibility and future-proof format

First, create the feed in Jekyll

If you’re using a different tech stack to create your website, you can skip this section and jump ahead to the part about creating an XSLT stylesheet.

You can either use the excellent Jekyll Feed plugin, or create your own template using liquid tags and save it in your project as feed.xml.

I chose to create my own template, so I could incorporate some additional markup. You can see my version below:

---
---

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet href="/assets/css/feed.xsl" type="text/xsl"?>
<feed xmlns="http://www.w3.org/2005/Atom">

 <title>{{ site.title }}</title>
 <link href="{{ site.url }}{{ site.baseurl }}/feed.xml" rel="self"/>
 <link href="{{ site.url }}{{ site.baseurl }}/" rel="alternate"/>
 <subtitle>{{ site.description }}</subtitle>
 <updated>{{ site.time | date_to_xmlschema }}</updated>
 <id>{{ site.url }}/</id>
 <author>
   <name>{{ site.author.name }}</name>
   <email>{{ site.author.email }}</email>
 </author>
 <rights type="text">Copyright © {{ site.time | date: "%Y" }} {{ site.author }}. All rights reserved.</rights>

 {% for post in site.posts %}
 <entry>
   <title>{{ post.title }}</title>
   <link rel="alternate" href="{{ site.url }}{{ post.url }}"/>
   <updated>{{ post.date | date_to_xmlschema }}</updated>
   <id>{{ site.url }}{{ site.baseurl }}{{ post.id }}</id>
   <summary>{{ post.description }}</summary>
   <content type="html">{{ post.content | xml_escape }}</content>
 </entry>
 {% endfor %}

</feed>

Note on YAML Front Matter block: It’s important to leave the dashes at the top of the file. This is necessary because Jekyll will not process a page with Liquid unless there is a YAML block at the top of the file.

Enable auto-discovery: Make sure you add the appropriate meta tag to support automated discovery of your feed. Place the following code somewhere in your template’s <head> section to output the necessary metadata:

<link type="application/atom+xml" rel="alternate" href="{{ site.url }}/feed.xml" title="{{ site.title }}" />

Create the XSL file to style the feed

We can use XSLT to style our XML. This makes our feeds more human-readable while supporting bots, aggregators, and search engines.

You’ll notice some similarities to HTML and CSS in the example below, but with a few semantic changes and special attributes.

First, you can place your CSS in the <style> tag like normal. You can also use some standard HTML markup like the <body>, <section>, <p>, and <h1> tags.

There are a few special elements you can use, like <xsl:apply-templates> or <xsl:value-of>. I won’t cover these in detail during this tutorial, but W3Schools maintains a great XSLT reference if you want to learn about all these special elements.

This Github Gist shows an example of the XLST stylesheet I created for my website. I wrote some basic CSS styles to format it, but you could even tap into your site’s primary CSS file to keep the styling consistent.

Save your file as feed.xsl and add the tag below to your XML file. Make sure the href tag points to the correct location and file name for your website.

<?xml-stylesheet href="/feed.xsl" type="text/xsl"?>

Conclusion

With a little extra care and attention, we can improve the experience of using RSS and Atom feeds across the web. Now when you visit my feed, you are greeted with an explanation of how to get started and a formatted recap of my latest posts.

I made my own XML template and XSLT stylesheet based on the examples above. You can see it in action here or download a version to adapt for your website.

Thanks for reading!

Additional Reading

How I built my blog with Jekyll and Netlify

2021-12-20T00:00:00-08:00

I’ve been blogging and hosting my website since 2006, but I’ve always been unhappy with the themes available for technologies like Blogger, WordPress, or Squarespace. I usually had a vision for what I wanted to create and would spend hours scouring marketplaces to find something that came close.

At first, I experimented with developing child themes for WordPress. If you’re not familiar with WordPress, I basically overwrote the CSS stylesheets and built my own page and post templates using PHP. I even got good enough that I had clients who would hire me to make changes to their WordPress themes and installations.

Still, all of the tweaks and changes felt cobbled together. They were cobbled together. I was building Frankenstein sites with dozens of overrides, plugins, and hacks that could break at any moment.

Searching for something better

I wanted to escape the bloat of platforms like WordPress, or the restricted design options available with a platform like Squarespace. I wanted to go back to static HTML and CSS and I wanted to code it myself.

After reading online, I came across Jekyll. It’s an open-source static site generator. That means it complies basic text files into static HTML so you don’t have to code every page by hand.

I built a few starter projects with Jekyll and quickly fell in love with it. While there are a variety of open-source static site generators available now, I still enjoy the relative simplicity of Jekyll for getting started. The liquid templating language is easy to understand and your HTML/CSS/JS work cleanly together.

Jekyll may not be the sleekest option — there are good reasons to pick something like Gatsby or Next.js if you work with javascript and react — I still think it is the most approachable option for beginners (like me).

To use a CMS or not?

I built a few starter websites with Jekyll. One of the things I missed at first was the integration with my writing tool of choice (Ulysses). I also wanted some of the benefits of a CMS, like scheduling posts. Ulysses integrates with WordPress and Ghost so you can publish from mobile and desktop. I decided to give Ghost a try.

As a CMS, I did love Ghost. It’s simple and focused on the writing experience. They have even embraced the Jamstack (Javascript, APIs, and markup) movement driving static websites and supporting headless designs. I also liked the idea of keeping my content separate from the frontend framework.

I worked with Ghost for a while but kept getting frustrated with the server upkeep that it invariable entailed. At first, I paid for a monthly subscription, but the functionality at the basic level is limited unless you spend $30/mo. At that level, you can either create your own theme to host with them or use their API to support a frontend framework built with Jekyll, Gatsby, or another tool. The cost is about the same as a good WordPress hosting provider, but that was more than I was willing to spend for the convenience of scheduling posts within a CMS.

I should note that Ghost also offers an option to self-host (starting at $5/mo through Digital Ocean) but I didn’t want to maintain the server myself. I already have enough reasons to not write without throwing in server updates…which were one of the reasons I wanted to leave WordPress.

Ultimately, I decided to forgo the CMS and focus on Jekyll. I’ll write more about this in the future, but Jekyll fits into my growing philosophy around working with markdown for personal knowledge management and publishing.

Publishing with Netlify

My first Jekyll website was published using Github pages. While I loved the option to publish a free project website directly from my repo, it was definitely more difficult to manage and came with a host of limitations.

Ultimately, I went with Netlify. They are a fantastic organization that makes it easy to build, deploy, and scale web projects. Using Jekyll, I can generate a website from my repo on Github and Netlify deploys it to edge servers across its network. Since I’m only serving static HTML files, this makes my websites incredibly fast for readers. And there is no server (on my end) to worry about securing, protecting, etc. Netlify handles the build and deploys the static files acrss the edge.

Getting set up

I won’t go into too much detail on the development process here, but I will link to the resources that I found the most helpful for getting started:

Poole: Clean and concise foundational setup for Jekyll
How to deploy Jekyll with Netlify
How to deploy Jekyll with GitHub pages
Formspree: Open-source form solution for static websites
Liquid template language reference from Shopify
Getting started with Netlify

As one of the original static website generators, Jekyll benefits from a large community of open-source contributors and users who have documented their techniques and solutions. If you get stuck, there is most likely a tutorial with the answers you need!

What’s next

Overall I’m pretty happy with the results of the project. I learned a lot along the way and ended up with a website that doesn’t look too bad and is unique to me. While I don’t need to make any changes to start writing, there are a few areas I plan to explore in the coming months:

Implement Tailwind CSS to replace Bulma I used the Bulma CSS Framework to scaffold the development of this project. Previously, I used Bootstrap for a few starter projects. Bulma is great, but I’ve been wanting something easier to customize. Enter Tailwind CSS, which is a just-in-time, atomic framework for creating CSS. I can build and design the website, all within HTML. Then, I can filter out any unused classes, resulting in a very small file.

Update 2024-12-01: I completed this work back in May 2022. I am currently using the excellent jekyll-tailwindcss plugin to implement Tailwind CSS for my site. I wraps the Tailwind CSS CLI and lets you specify which version of Tailwind CSS you want to use.

Buildout functionality for my digital garden I expect to write about this more in the coming months, but I’m planning to treat this blog more like a digital garden. There are some core functionalities I want to add, like sides notes, bi-directional links, and search, to make the reading experience more rich and interconnected.

Update 2024-12-01: I’m still working on this. Overall this feels a bit more like a distraction from writing than a priority. I have played around with introducing categories for evergreen, seedling, and budding notes to indicate how complete an idea/post is.

Rebuild the site with Gatsby, Next, or another framework I really like Jekyll, so this one isn’t urgent. But I’m starting to see how javascript frameworks like Gatsby, Next, or Vue could enable some new capabilities. One function that stands out to me is the ability to import markdown (my blog posts) from a separate Github repository. This way my thinking and writing could truly exist separately (and under version control!) from the frontend visual design.

Update 2024-12-01: I no longer plan to do this for a variety of reasons. I may write more about why in the future, but the short version for now is that I hate dependencies and heavy frameworks. I like how simple Jekyll is to run, and that the final result is really just a bunch of html files, one stylesheet, and one bit of non-critical, vanilla Javascript.

I hope you have a similar positive experience, and please reach out if you have any questions about building your website with Jekyll and Netlify.

Andrew Stiefel

Building a personal monorepo for writing

Why use a monorepo?

Basic Setup

Configuring Obsidian

Connecting Jekyll and Obsidian

Publishing with Netlify

Final Workflow

Bonus: Convert Backlinks to Weblinks

Additional Resources

AI isn't taking your job — the economy is

A Correction Disguised as Innovation

From Tech to Biotech: The Narrative Spreads

So what is AI doing to jobs?

The Bottom Line

How I use GitHub as a CMS

Why?

Basic setup

Use issues to track posts

Writing and publishing posts

Final thoughts

Further Reading

Markdown files, not apps

Markdown is simple

Markdown is portable

Markdown works offline

Markdown is ready for AI

Conclusion

Principles of platform independence

1) Cross-Platform Compatibility

2) Data Ownership

3) Data Portability

4) Logic Separation

5) Local Control

Dead internet is no longer a theory

Meta looks into the black mirror

Navigating the dark forest

Back to IRL as the norm?

The myth of the average user

Weighing in on AI hype and risk

Newton’s argument in a nutshell

A false dichotomy

Sorting out risk from hype

Final thoughts

How to package new product features

1. New Product or Tier

2. Add it to an Existing Tier

3. Make it an Add-on

4. Do Nothing/Kill the Initiative

Working with multiple GitHub accounts and SSH keys

Organize your local directory

Set your global gitconfig file

Create gitconfig files for each directory

Configure the SSH agent

Reset your local repositories

Resources

Thoughts on information fidelity and transmission

Why does this matter?

What does this look like in practice?

Closing Thoughts

Writing for technical audiences

Know your audience

Use clear language

Provide evidence

Give concrete examples

Use visuals

Incorporate storytelling

Summary

Additional Resources

Thoughts on open-ended writing

Digital Gardening and Small b Blogging

A Brief Definition of Open-Ended Writing

Some Spring Cleaning

How do you practice open-ended writing?

Pocket guide to privacy-first email newsletter software

Privacy-First Email Newsletter Services

Buttondown

SendStack

MailCoach

Conclusion