Blog on Kevin R. Kuhl

Paul Osmon: "Building the Web"

Mon, 09 Mar 2026 13:31:00 -0400

Paul Olson is a software engineer with a background in platform engineering and observability, and is working on an engineer’s history of web architecture. Here’s how he describes the project:

The years spanning from 1993 to 2015 were extraordinary. Linux and FreeBSD became mainstream server operating systems, the NCSA httpd project was released, it begat the Apache HTTP server, which in turn inspired projects like nginx. The world saw the birth of a global network for information exchange and its evolution into the substrate of our everyday lives. We went from editing files and placing them in directories on a server to shipping fully containerized applications through complex pipelines. Client-server architecture became three-tiered architecture, eventually morphing into the microservice death star diagrams shared in conference talks as humble brags about the amount of infrastructure required to run large sites. Most of this innovation was done in the open, often by people collaborating across organizational and geographic boundaries. I owe my career to this time period and to the people who shaped it. The amount of knowledge sharing and learning, between practitioners figuring things out the hard way, that has happened during this time period is staggering.

I’m writing a book detailing the major shifts in web architecture that happened during this time period. Things continued to happen, of course, and 2015 is admittedly a bit arbitrary — but I chose this timeline because we had containerization and orchestration cemented. Much work that has happened since has been focused on ML / AI, which is out of scope for this project. I’m writing the book because it’s important to illustrate the connective tissue between these developments. It’s also important to appreciate how these contributions were made by practitioners working in specific contexts under specific constraints, and how their innovations compounded — sometimes unexpectedly. I want to dive into how the industry evolved from stateless web servers serving static documents through the C10K problem, through developments in caching reverse proxies, improvements to OS kernels, experiments with new programming models, infrastructure like CDNs, and beyond. I’ll treat security as a common thread that runs through each chapter, with each innovation addressing some challenges and introducing new attack surface area for others.

I think these kinds of projects are immensely valuable. Building an account of why things are the way they are, from the perspectives of people working in the trenches can leverage insights that are valuable for future projects. For those of us working in software engineering today, understanding this perspective is a form of architectural forensics. You can’t truly understand why a system is complex until you understand the problem it was originally designed to solve.

It’s also valuable for people outside of the world of software — while Osman’s intended audience is engineers, academics really benefit from this sort of undertaking, we can better understand the shape the web is taking when we understand that technologies aren’t inevitable, but responses to specific problems.

The book will be released progressively at buildingtheweb.dev, and you can following along by signing up at the site, or using your RSS reader of choice.

Quick aside — I’m planning to ramp up the frequency of these posts. There are some big (and very positive) changes in the works professionally. Expect a bit of an adjustment period, followed by a lot more technical deep-dives and interesting links!

Generating Event Feeds with Hugo

Tue, 10 Feb 2026 00:00:00 +0000

While I’ve been looking for my next professional thing, I’ve been working on a community organization side project. The idea is to support a community group with recurring events, allowing people to come together to share skills, knowledge, and build relationships. Ordinary human being stuff.

But if you’ve been following my blog, you know that I have an opinionated view on social media. I’m begrudgingly planning on using Instagram to reach people, but I think that organizers and communicators should build things that are independent of major platforms. This lets you pick up and take the resources elsewhere if you need to. And when it comes to distributing information, I like platforms where people can subscribe and control how they get updates — where users pull rather than receive. This means I’m not responsible for adding or removing subscribers. You’re responsible for subscribing and filtering as a user.

Meetup is not my favorite platform, though it’s widely used. Luma is pretty widespread in the tech community in my area. Eventbrite is also a possibility.

But I enjoy using Hugo, and I’ve already built a script that lets me syndicate blog posts to Bluesky and Mastodon. Building an events calendar in a Hugo site is a natural next step.

Caution! This is written for an intermediate Hugo user. You don’t have to be an expert, but I’m going to move through some details without explaining everything at a beginner level. I’m hoping that this will land with people who like building with static site generators. If there’s interest for an intro to Hugo post, let me know?

Static site generators and iCalendar

Hugo is a static site generator. It takes markdown files (with metadata stored as “front matter” before the content) and generates folders, HTML, and XML that make up your website. It’s inexpensive to host and deploy the website, since a visitor is only requesting text and image assets when they visit your site (and maybe some JavaScript). It’s quick and (relatively) simple. Most importantly for this project you can define custom output formats that pull data from the front matter of your markdown files.

iCalendar (Wikipedia and the spec) is a standard format for calendar entries. Like most things on computers, .ics files can be viewed in calendar apps or as plain-text files. Hugo supports the ability to build to custom output formats. Using Google Calendar, Outlook, Thunderbird, or the MacOS calendar app, you can subscribe to URLs that regularly post events. It’s kind of like RSS in this respect.

Using Hugo, I can post all of the following things whenever I plan an event:

A blog post with key event details.
A corresponding .ics file so attendees can download the event information and add it to their calendar.
A corresponding RSS feed for my calendar posts, so followers can know when new events are added to the website.
A corresponding .ics calendar file, so people can subscribe to the calendar and receive updates in their personal calendars.
Bluesky and Mastodon posts, using my POSSE script.

This is a low cost way of getting one-to-many communication where users can opt in and out without having to worry about maintaining a mailing list. If I’m using Canva for promotional images for Instagram, I can store the instagram text and images in the same project folders (Hugo page bundles). The website becomes the source of truth for everything I’m doing to coordinate events. When I want to promote the event, I can share a QR code for the individual event pages.

The only part it’s missing is tracking attendance and interest. This is not something a static site is particularly well suited to doing. My plan for this is to use some kind of third party form service and monitor engagement with social media accounts. Keeping data collection minimal means that it’ll be easier for me as an organizer — no user accounts or mailing lists to maintain.

Some technical details

Hugo uses Go as its templating language. I wouldn’t consider myself a Go developer, but the syntax isn’t that difficult. We’re mostly going to be referencing variables in template files. This lets Hugo build output from your markdown content.

There are a couple of important technical details that we need to keep in mind about the ICS spec before building this out:

Whitespace is structurally significant: In Hugo, it’s tempting to strip all the whitespace in files to keep things small. In iCal files, properties like BEGIN:VEVENT have to start on fresh lines.
Timezones: Calendar apps expect timezones in UTC (with the Z suffix), so when I’m setting up the templates and creating event content, I will want to add a validation script that ensures I have valid date-times.
Stable UIDs: Hugo has a value called .File.UniqueID that lets me call the UID based on the content file. This way, when I rebuild the calendar, subscribers won’t end up with duplicates for each rebuild.

Implementation details

That’s the big picture, now I’m going to get into the details, starting with how I plan on structuring content for the website, defining site level configuration features, and the custom elements that are necessary to make this work.

Content structure

First, I needed to create a dedicated branch in my content directory. I used a branch bundle (_index.md) file to apply specific metadata across the entire section, including my new output type:

---
title: "Upcoming Events"
outputs:
	- HTML
	- RSS
	- ICS
---

By default, Hugo can output RSS for sections of your site, but it doesn’t have templates or resources for creating ICS files. To do this, we’ll have to add the output type to the site level configuration, and create template files.

Custom outputs and configs

Your sitewide configuration is typically handled in hugo.toml or config.yaml. To add ICS:

[outputFormats] 
	[outputFormats.ICS] 
		mediaType = "text/calendar" 
		baseName = "events" 
		isHTML = false 

[outputs] 
	section = ["HTML", "RSS", "ICS"]

[minify.tdmt]
  "text/calendar" = false

The media type format is important! This [outputFormats.ICS] block tells Hugo to build the file with metadata in a way that won’t confuse browsers. You need to add the baseName to ensure that the format picks up the right resources. I also added a line to my config to prevent minification for the ICS type. Minification reduces the size of files to make things more streamlined for machines, but this can cause problems with the ICS file type

Archetypes

Archetypes are used by Hugo as a template for new content files in a category. If I add an events.md file to my archetypes folder in the project directory, the hugo new events/{event-name}/index.md command will generate a markdown file from that archetype.

This lets me standardize the metadata for new event posts to my website, and start filling in the content for an event page:

---
title: "QFC {{ replace (replace .Name "-" " ") "qfc" "" | title }}"
date: {{ .Date }}
event_date: {{ .Date }}
event_end: {{ .Date }}
location: "TBD"
is_virtual: false
---

### Event Details
* **When:** {{ .Date | dateFormat "Monday, Jan 2, 2006" }}
* **Where:** {{ .Params.location | default "TBD" }}

For the title parameter, I have a replacement block that’s using the acronym for the project that I have in mind. The other parameters are filler that will be generated by Hugo. After running the hugo new events/{title}.md command, I’ll need to change the event_date and event_end values to those for my event, since currently I’m filling that with the current date. As I noted, it is important to handle timezones carefully! When updating the date fields, we need to be sure to include my timezone offset -05:00, so I can handle that with the Hugo build process.

If I write a validation script, I can specify my timezone, and check both event_date and event_end for proper formatting.

The other big thing to bear in mind is whether it is currently daylight savings time. My timezone shifts (-05:00 or -04:00). Depending on whether it’s currently DST. Maybe this is something I can handle with the archetype, but for now, it might be something I’d add to the validation script. I’m a big fan of using a Python script for local checks before I deploy my Hugo site to the web, so this is something I can tailor around my own needs.

Layouts

Layouts control how Hugo renders different formats when building the site (when you run the hugo command for your project). To do this, we’ll have two separate layouts added to my custom folder.

Calendar feeds

ICS entries have a fairly simple structure. There’s an initial block of front matter:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//{Your Name or Org}//Hugo//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME: {Your Calendar Name}

Which covers the information about the calendar as a whole — the product that builds it, scale, it’s name, and timezone.

For individual events, we will want to instruct the layout to build the following for each page in the section:

BEGIN:VEVENT
UID:
DTSTAMP:
DTSTART:
DTEND:

SUMMARY:
LOCATION:
DESCRIPTION:
URL:
END:VEVENT

And signal the file-end with:

END:VCALENDAR

Since I’m not worried about having a particular place in my site structure for building the ICS files, I’m going to define my layout in the _default folder. This way I could build a calendar for any section. As a Hugo layout (_default/list.ics), this looks like:

{{- $pages := .Pages -}}
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Your Name or Org//Hugo//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:{{ .Site.Title }}
{{ range $pages -}}
{{- if .Params.event_date }}
BEGIN:VEVENT
UID:{{ .File.UniqueID }}@{{ $.Site.Title | urlize }}
DTSTAMP:{{ now.Format "20060102T150405Z" }}
DTSTART:{{ (time .Params.event_date).UTC.Format "20060102T150405Z" }}
{{ with .Params.event_end_date -}}
DTEND:{{ (time .).UTC.Format "20060102T150405Z" }}
{{- end }}
SUMMARY:{{ .Title | replaceRE "([,;])" "\\$1" }}
{{- with .Params.location }}
LOCATION:{{ . | replaceRE "([,;])" "\\$1" }}
{{- end }}
DESCRIPTION:{{ .Summary | plainify | htmlUnescape | replaceRE "\n" "\\n" | replaceRE "([,;])" "\\$1" | chomp }}
URL:{{ .Permalink }}
END:VEVENT
{{- end }}
{{ end -}}
END:VCALENDAR

I’ve set the calendar name to pull directly from the site title. One of the most critical pieces for a reliable subscription feed is the UID; by using {{.File.UniqueID}} and programmatically appending the site title, I can ensure that every single entry maintains the same ID across every build. This prevents your calendar app from getting confused and creating a mess of duplicate entries every time I push an update.

The timezone shift is where things get a bit “crunchy.” Using DTSTART:{{ (time .Params.event_date).UTC.Format "20060102T150405Z" }}, the template grabs the date from the front matter and forces it into the “Zulu” format that general calendar apps expect. This means a timestamp like 13:00:00-05:00 gets converted into a computer-readable format, so everyone sees the correct local time regardless of where they are. DTSTAMP is set to the time that the file was created, so handling is a bit easier.

I’ve also baked in some filters to handle characters like commas and semicolons, which act as delimiters in ICS files. By automatically adding a backslash to escape them, we prevent the data from being cut off mid-sentence. Similarly, I’m using plainify to strip out any HTML tags that Hugo might normally generate, keeping the event description simple and in plain text.

Finally, the layout is very intentional about whitespace. I’ve used hyphens inside the code blocks to surgically strip away extra whitespace and empty lines where they don’t belong, while leaving them off structural lines where a fresh newline is required by the spec. A quick chomp at the end clears out any trailing newlines in the description, ensuring the final output is as lean and spec-compliant as possible.

Events pages

Hugo uses layouts to also build the default HTML for a list of pages, and the individual pages within the category, we add a similar layout for the individual pages to generate an .ics file unique for each event.

The single page layout looks like this:

{{- $event_time := time .Params.event_date -}}
{{- $end_time := ($event_time.Add (time.ParseDuration "1h")) -}}
{{- with .Params.event_end_date -}}
  {{- $end_time = time . -}}
{{- end -}}
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Your Name or Org//Hugo//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:{{ .Title }}
BEGIN:VEVENT
UID:{{ .File.UniqueID }}@{{ (urls.Parse .Site.BaseURL).Host }}
DTSTAMP:{{ now.UTC.Format "20060102T150405Z" }}
DTSTART:{{ $event_time.UTC.Format "20060102T150405Z" }}
DTEND:{{ $end_time.UTC.Format "20060102T150405Z" }}
SUMMARY:{{ .Title | replaceRE "([,;])" "\\$1" }}
LOCATION:{{ (.Params.location | default "TBD") | replaceRE "([,;])" "\\$1" }}
DESCRIPTION:{{ .Summary | plainify | htmlUnescape | replaceRE "\n" "\\n" | replaceRE "([,;])" "\\$1" | chomp }}
URL:{{ .Permalink }}
END:VEVENT
END:VCALENDAR

The biggest change is that I handle the event time using variables. I wanted to include a fall back: by default events will last one hour without a specific end-time. The template tells Hugo to override this default, if it finds a value in the front matter. Why? This ensures that events have the data that some calendar apps expect.

Otherwise, things are pretty similar to the calendar feed — since it’s for a single page, it doesn’t have to loop through the pages that are available in the section.

Why not h-events?

The IndieWeb standard for events is h-events. The central idea is that these are series of standard HTML and CSS elements that allow for interoperability between sites. It’s a cool idea — but it’s dependent on people in my target community working with IndieWeb tools and standards.

Basically you could handle things like RSVPs through “web mentions”, which enable automatically listing attendees, or these events could appear on IndieMap. It’s very cool, but also a little more techy than my target audience. If this was a developer skill-share, where my audience was already a bit more IndieWeb savvy, this would make sense. If I really wanted to do this, I’d add this to the layout for the HTML page generated by Hugo.

The idea of going to an ics feed is important for reaching people with the devices they have at hand — they can add the event to their calendar apps. Extending this to include the h-events elements in my sites HTML wouldn’t be too hard, but it’s not necessary for my audience. We’re prioritizing connecting with people in an immediate region who use phones, and Outlook and Google Calendar.

The workflow

Now when I want to add an event to this groups calendar, I do the following things:

hugo new events/qfc-001-welcome-to-qfc/index.md

And fill out the relevant details, such as the date, time, venue, etc. I’ll also go to my form service to generate an RSVP form so i have a sense for the numbers of attendees and any needs or requests.

Then I run my build script:

python build.py

Which builds and deploys the site to its hosting service. Having a build script brings together several command line steps, including:

Clearing the public directory
Building the site
Deploying the site to my server
Running my POSSE tools to syndicate the event to Mastodon and Bluesky

I’ll still have to promote the event on Instagram, but this way the event is published to my site, including calendar and RSS feeds. Members of the community can add the feed to their calendar apps on their phone, and the event details will be there for them.

The resulting file directory will look like:

.
├─ public/
|	└── events/
|	   ├─ index.html
|	   ├─ events.ics            # <--- This is the feed. 
|	   └── qfc-001-welcome-to-qfc/
|	  		├─ index.html
|	  		└── events.ics          # <--- This is the single event.

If you really want to get into content modelling with Hugo, you can define section specific layouts for pages within your calendar (the list and the section page) that include UI elements which link to your calendar. In my project, these live at ./layouts/events/list.html and ./layouts/events/single.html Using the webcal:// protocol for the calendar feed link (instead of https://) will prompt users to subscribe to the calendar feed, and they’ll receive updates when their calendar app refreshed the feed from your website.

Here’s how this is looking in my proof of concept:

Repeatability?

The initial build out took about an afternoon of playing around and I think it’s pretty powerful. Refining it took a bit more time, but I’m pretty happy with the results. There’s a real problem with event organizers primarily relying on Instagram and Discord in my area, so hopefully more and more folks will look to tooling like Hugo or Ghost to maintain a presence for their groups and events.

If you’re comfortable with building in Hugo, please feel free to use these layouts in your own site. I’ve tested it with Thunderbird, Google Calendar, and MacOS applications. If there’s enough interest, I can set up a repository that includes templates for an events section on typical Hugo sites.

One thing I’m considering doing with this is creating a playbook: how to create your own blog and event feed for community organizations. Hugo is a little technical, but I think I could make this repeatable for community organizations. If you couple it with Decap/Static/TinaCMS (as a kind of CMS or even Obsidian and Github Desktop), and Github Actions, this becomes a pretty powerful way to run a community site. I still think it might be a bit too technical in the long run, but I’d really like a vibrant collection of local websites that I can tap into using browsers, calendar apps, and RSS readers to distribute information.

If you’re trying to implement this and want to talk about the details, please reach out to me!

RSS, Syndication, and the Future of the Web

Tue, 03 Feb 2026 00:00:00 +0000

My love of RSS is something I’m not shy about. I think it’s a pretty excellent one-to-many communication tool. But what’s interesting is if you look at its history, it had one major flaw (that’s also partly why I love it). And in many people’s minds, RSS is a dead technology.

This blog post came directly from a slack discussion with the local tech scene that went a little something like this:

NewsletterAuthor: I've migrated my newsletter to Ghost! Here's the new URL.

Kevin: Oh cool! For those of us using RSS readers, here's the new feed URL.

OtherUser: Wait, didn't Google kill RSS?

So, this post is going to be a bit of a “what is RSS?”, “is RSS really dead?”, and “what’s going on with syndication on the internet anyways?”

I think we’re at an interesting inflection point between a couple of different directions, and we could progress in a way that returns a lot of power to content creators. The pendulum is swinging back to a utility based economy from an attention based economy, and this is a good thing, even if we’re in a moment that’s painful for the ad-revenue based paradigm of the 2005-2025 world.

This post is my potted history of communication technology, and why I think things are improving for individual creators.

This is a deep dive. Here’s the tl;dr:

RSS isn’t dead; it just became the invisible plumbing that powers the entire podcast ecosystem. We “killed” text RSS because it abstracted away the ads and revenue for blogs and news, but audio RSS was baked in due to bandwidth limits and how listening let creators bake ads into the media (unlike blogs).

We’re seeing a migration from walled gardens (Substack) to owned platforms (Ghost) driven by “Subscriber RSS” — that lets readers support creators directly while still reading their work in your app of choice (shout out to 404 Media for nailing this).

The future isn’t just humans subscribing, though. With the rise of “agentic browsing,” AI bots don’t look at ads. Instead, they’ll likely use protocols like HTTP 402 to pay micropayments for access to data (or subscription to content APIs or MCPs). The internet is moving from an attention economy (ads) back to a utility economy (paid delivery), and protocols are the only way that works.

What is RSS?

RSS stands for really simple syndication. The wikipedia article is a really nice historical introduction to the concept, that goes into the history more carefully. But I want to introduce the concept and a bit of history.

Here’s how the internet works, in a really simple kind of lens:

You have a computer, which has a piece of software known as a web browser.

If you’re publishing content to a website, you typically do so in a format for a web browser. It’s published as HTML and Javascript (and likely talks to some computers elsewhere for images and other things), which is collected together and rendered as a formatted experience inside of Chrome, Edge, Firefox, Opera, etc. In this case, what’s curated for you is the visual experience of a website.

When I want to see what content you have published on your website, I start up my computer, and I open my browser, and type the address on your website. My browser makes a request to your server, and it returns HTML and Javascript for your website which displays as a page. How this appears is determined by files that describe the overall style of the content (CSS).

Both of us have the costs of running our computers (electricity, hardware), and costs for sending and retrieving data over the internet.

But what matters to me as a reader isn’t really how you’ve chosen to style your writing. In fact, rather than going about making requests to a bunch of servers myself, it’d be much nicer for me as a human being if I had an application that would make those requests for me, and I could view the bits that I want, all inside of that app, with uniform styling. If there was a uniform way of building content that apps could read, that would help readers consume content.

It was an attractive idea back in 1995. But it has evolved a bit over time. The fundamental idea is that you can markup the essential elements of a site using XML and plain text, build that into a feed, which can be retrieved by a separate application or portal. Originally, This was built for use in Netscape, but with Netscape’s acquisition by AOL, it has an interesting history of parties trying to revive and maintain the standard.

This history is why Atom, a different standard, similar to RSS was created.

But basically, as of about 2005, RSS was an initial syndication standard for mainstream technical blogs. Companies like Google were releasing applications that allowed you to save and access lists of RSS feeds viewing content from multiple websites in a single portal, arranged chronologically.

It became a vital part of how I used the web, reading web comics, blogs, and more. With an RSS reader, I can open up a single page, and see news and posts from multiple sources, organized in a way that lets me direct my attention without distractions.

The “Murder” of RSS

I put “murder” in quotes, since I think RSS survived. More on that later. But a few factors lead to the decline of RSS in the 2010s.

Google Reader was the most popular RSS reader. It was added to the Google graveyard in 2013. I was using it heavily. But I was also hitting the point where I was seeing too much content in my feed. for it to be something I could stay on top of. There was definitely a saturation point for blog content.

So, how does a website make money? After all, it costs money to run a server, and send HTML to all those browsers visiting your pages. The answer was advertisements. By embedding advertisements on your website, you can get paid based on the amount of traffic you have for your website.

At the same time, social media was rapidly expanding. We were viewing feeds of content about the lives of our friends and family. And that would include news and eventually community pages for people who were trying to build a following. If you ran a media company, you could pay to get traffic directed to your site, but you were also hoping that things you posted would go viral. Traffic would come to your site, and you’d be paid based on the number of people who spent time on your site, or clicked on blog posts.

Marketing was the vehicle which funded content creation and content creators were leveraging social media platforms to get their content to their readers. Cory Doctorow talks about this as the “enshittification” of platforms.

Where did this leave RSS and Atom? if your ads were served in Javascript powered widgets on your website, they wouldn’t easily be loaded in your content. So maybe you start to truncate the content that makes it into your RSS feed to drive traffic to your website. Or maybe you rely on merchandise sales to support your webcomic or your blog. Gradually speaking, the utility of your RSS reader decreases from a place to read content to a place to drive traffic. Your time is better spent on your social media strategy since social media is getting more and more attention.

This was the main attack on RSS from companies. Largely one driven by financial incentives, where companies tried to maximize the capture of attention to sell ads and drive revenue growth based on a non-paying user base.

A major blow was when Google retired Google Reader. There were other readers available, but they often operated on a subscription model to get more fully powered features that let you keep up with scale. Meanwhile, algorithms were getting stronger on Twitter and Facebook, so both discovery and delivery would occur on those platforms. Advertising supported platforms like Feedly, but it wasn’t able to grab a significant portion of the user base of Google Reader. Self-hosting was not as popular and RSS became more and more of a curiosity.

For many people, if they have an RSS feed at all for their website, it’s vestigial and they’re barely aware it exists. Or you were a bit of a weird legacy tech nerd trying to reach other tech nerds. This was exactly the dynamic that inspired writing this post!

What about audio?

Podcasts are a cool technology. It’s interesting to think a bit about why podcasts are the way they are, while other forms of media didn’t go this direction.

The biggest piece of this puzzle is how people were consuming audio vs. text and bandwidth limitations. Back in the days of lower data caps it was common to have a separate device (mp3 player) to listen to music, lectures, or other kinds of long-form audio content. Because your cable or high-speed internet provider had larger data limits than your phone, you could download more audio without running into the hard limits on your smart phone.

iTunes was a nascent marketplace for music, but there were also people publishing audio content to various websites. RSS readers let you collect updates from those websites. By having an excellent MP3 player, RSS became a way to get an excellent ecosystem of content onto that device, without Apple having to build their own marketplace/database.

RSS and iTunes 4.9 were the key to unlocking this idea. Basically an intermediary app became the way to deliver audio content to your device. Instead of checking for updates, these would be automatically loaded to your device whenever you were charging it via USB at your computer.

If you wanted your audio to be available to people on their iPods, RSS became an easy way to access that market. It was also easy enough to adapt as mobile internet caught up to delivering audio.

What’s kind of wild is that podcasting emerged and stabilized largely because of bandwidth concerns. Audio is relatively cheap - hosting and delivering 60 minutes of audio (~50 MB) to 10,000 users is manageable for a server. But 5 minutes of video is 200 MB and the costs of video going viral could bankrupt a company. “Vodcasting” was almost a thing, but Youtube and Google really altered the trajectory here. That’s another story.

It’s also worth remarking on the behavioural differences between audio and video too - video requires visual attention, while podcasts can be listened to on the commute, while on a run, or while doing dishes.

In a way, audio was perfect for RSS syndication because of its mode of communication, the size of the files, and the variety of devices that could play these files.

Why do podcasts “work” when blogs don’t?

There’s a couple of reasons.

At first glance, it’s very tempting to attribute it to attention. When you listen to a podcast, it’s more difficult to skip past promotional content. You listen to the podcast from start to finish.

The monetization between blogs and podcasts is strikingly similar though. You have the following options really:

Advertisements
1. Paying for views/clicks
2. Referral link payout
Subscriptions
Sales of merchandise or other services.

And I’ve seen this play out in both blogs and larger podcasting services. I think the biggest reason why podcasts work while blogging fell apart has to do with the portability of attention. Reading a blog post requires visual attention while listening to a podcast can be done on the go.

if you have to spend time visually attending to your RSS reader and Facebook to get information, and Facebook has teams of PMs, developers, and UX designers building a system to maximize your attention for ad revenue. On the other hand, RSS readers fundamentally abstract away from revenue generating mechanisms, syndication for text was fundamentally doomed.

The big thing is that in these environments algorithms shape what content is presented to users, and these algorithms are built to maximize ad revenue, which is secured by keeping people on the platform. External links get downgraded, unless it’s a service that could be paid for, but then people only really engage with advertisements that are well targeted to them. Basically monetization by advertising revenue could be maximized in an environment where companies could control what you see. And multimedia is a way of grabbing attention.

Gradually the expansion of multimedia as a means of grabbing attention reduced the share of blogging. These platforms, driven largely by advertising as a means of monetization, began to choke out websites as an economically viable thing. Browsers and operating systems began to have news items baked into the interface, trying to bake attention and advertisements into how you access the web. And news media continued to maintain websites, but they gradually cut off RSS to focus on systems and sources where they could maintain revenue, which was dwindling rapidly. Capital began to aggregate news providers, and quality declined. Generally speaking, things looked pretty grim for people in media.

The actual story is a bit more complicated of course. Microblogging (Twitter/X, followed by Mastodon and Bluesky) was another form of Web2.0 that cut into the world of blogging, and Instagram also played a part. That and TikTok. The relationship of short form video to attention, marketing, and media consumption is a massive topic, but I’m going to try and limit this post to talking about writing. After all, I’m a writer and blogger.

Also, I’m just going to note that many podcast syndication services now insert ads into audio files based on information from the podcast app being used. Advertising on podcasts is a cool topic in and of itself!

Some countries (notably Australia and Canada) realized that this was pretty bad for the media ecosystem and made attempts to legislate that the social media giants and web platforms contributed to regional media ecosystems.

This backfired and there were interesting results like garbage collection companies becoming de facto local news, posting short videos and getting engagement on social media. As a Canadian, it’s an interesting media landscape. Some of the strongest sources of local news come from perspectives not attached to my local newspaper.

Subscriptions and media

Ok, so newsrooms are failing, bloggers have moved to Instagram, Twitter and Facebook, and social media is thriving on advertisement revenue. There’s a bunch of talented writers who are displaced and can build a following, but need to monetize long-form content.

RSS/Atom are fundamentally ways of syndicating content that emphasizes delivering it to people who want to opt-in. But if you’re a creator looking to control who has access to content, they’re fundamentally open. If I post an RSS feed to my website, anyone with that URL can add it to their reader.

But if I build a website that allows me to collect the email addresses of paying subscribers, send them content on a regular basis, and control access to the content, I can get paid and distribute content. This is pretty great. I also get pretty solid analytics on subscriber numbers and readership rates (which helps with selling advertising, if I’m doing that). Some people picked up on the viability of offering this as a service to writers who didn’t have the technical chops to put together this kind of service (basically gluing together a CMS, payment service, and emailing platform), and recommending similar pieces of writing to grow the audience and subscription base, and voila, we have platforms like Medium and Substack.

These platforms can use their aggregated audiences and consumers to drive profitability, paying and supporting star writers, and subsidizing the service for smaller writers. They’re an interesting revival of monetized blogging, and are probably the most popular/widespread means of sharing writing for journalists.

Since writers need to build audiences, they use these newsletter platforms for syndication and subscription management, while building the audience through microblogging services, podcasts, and video media. Here’s Paris Marx talking about his journey with finding a provider for his newsletter (hoping that there would be network effects) and why he left (due to association with less politically savory folks and “profit pressure” making the environment less friendly to creators). We’ll come back to Ghost, but I think it’s really important to note that there are both platforms and self-hosted tools that let you build newsletters

The core tension is this: email isn’t really a preferred way to read long form articles, and accessing a site through log-in can be a bit of a pain for users. So authors need a way to control access to their content, while users want an easy pipeline to consume content. Newsletters let authors syndicate and manage. Feed readers and email providers become the way we choose to consume the content.

It’s interesting to watch, currently, how podcasting is faring in this current technological landscape. Spotify is an audio streaming platform that has started to pay high profile podcasters to get their audience onto the platform. Some podcasters monetize by offering premium subscription tiers with bonus content. Others form into networks or rafts of related podcasts to share advertising revenue.

In a real sense, the challenges of monetization for podcassts are the same that are being faced by bloggers. Which is why we see similar kinds of things happening to podcasters as in the latter days of blogging. Blog networks, subscription-based content, and membership communities are all strategies to build that revenue in ways that close the ecosystem off.

This tension will likely shape the media to come. So I want to talk about three trends that are breaking away from this landscape and where I think we’re headed.

Three trends

I think there’s three main trends for how the internet is evolving after Web 2.0 (I’m not going to talk about Web3 because of reasons):

Paid syndication outside of email — 404, Aftermath, and self-hosted newsletters.
Algorithmic choice and federated social media — Bluesky and Mastodon.
Paid access for crawlers — Cloudflare and generative AI-powered browsers.

A look at breaking away from platforms: 404 Media and paid RSS

So platform subscription services are falling victim to the usual profitability pressures. Here’s what I think is a useful model going forward: It’s becoming easier and easier to host and publish your own content to the web. While I use a fairly technically hands-on stack, it’s entirely possible to self-host a newsletter service for something comparable to paid hosting services. The overall challenge is balancing the cost of hosting against revenue coming in. And if I were trying to monetize this blog, I wouldn’t want to use invasive advertising. I’d either move to a platform that could handle subscription payments, or I’d look at some kind of passive sponsorship from a very specific sort of advertiser (rather than using traditional Web2 ad markets). Rather than rely on a network, I’d keep it at its own URL. Maybe it wouldn’t be successful, but if I have to enter into an agreement, I want it to reflect my brand the whole way down.

Ghost is a newsletter platform/CMS that is free-to-use. Many of it’s themes are optimized for newsletters, but you can easily use it to run something between a blog and newsletter. You’ll need to deploy a server and DNS, but in theory, you can use it without paying the creators directly. If you don’t want to muck about with that, you can also use their hosting (which has multiple paid subscription tiers based on the size of your audience). Either way, you own your own content, and can use your own domain name. As a newsletter service, you can break your content into publicly available, and available to subscribers. Posts can be sent to subscribers. And by default, it has RSS feeds enabled.

404 Media is a collective of tech journalists that previously worked for companies like Vice Media. They do high quality reporting on technology and society. And when Vice began to contract, they got together to create a small, independently owned site driven by subscriber access. Since they have an audience that is engaged and technologically focused, they had readers that use RSS readers to consume news from a variety of sources, and that forcing paying subscribers to log into a website is a poor user experience.

The solution is a “tokenized” RSS feed. When you subscribe to 404 Media, you get a unique, private RSS URL (e.g., 404media.co/feed/unique_token_123). This feed delivers full-text articles bypassing the paywall because the URL is the key. If you cancel your subscription, they stop posting the feed to the URL.

This stack uses Ghost, plus a stack that handles subscriptions and the management of tokenized feeds. And it’s cool to see this approach spreading to other collectives of journalists, such as Aftermath.

What’s great about this model is that it respects the users choice of reading environment, while protecting creator revenue. It treats the RSS reader as a first class citizen, not a pirating tool. As a user, this feels good. I know that I’m paying the creators directly for their content, but it’s quiet. I can review and see all the content from the site in an environment I have control over. It determines my pace of consumption and access, and I can rave and review things without the noise and intrusion of notifications from a social media interface.

It also allows the platform to own or control more of the stack. They decide which authors are publishing within the site (unlike Medium or Substack). It is a bit of an epicycle on the idea of subscription content, but I think it moves the needle forward for both readers and creators.

Bluesky and algorithmic choice

If RSS is “build my own subscription algorithm” and Twitter/X is “consume what the algorithm feeds me”, Bluesky tries to find the middle ground.

Under the hood, Bluesky runs on ATProto, which shares an outlook with RSS. It’s an open data standard for social media posts. On Twitter/Instagram/Facebook, your feed is a black box optimized to make you buy things. On Bluesky, the “algorithm” is just another feed that you can subscribe to. People build and maintain feeds with names like “Tech News”, “Cat Photos” or “Mutuals Only”. An open standard lets different federated servers share content, so in theory, you could have a separate app talk with Bluesky and you could access content from other services on Bluesky itself. It’s a seriously cool break from platform lock-in.

It’s possible to define your own feeds and lists, and switch between them. I’m subscribed to a local posters feed for the Waterloo Region. But the core idea is that curation is in your hands as a user, while you can still access a firehose of general content structured via ATProto. It’s syndication, with a customizable filter on top.

In addition to syndication, it’s possible to have your own servers which integrate with other publicly available ATProto servers. Mastodon is similar in scope and provision, with ActivityPub playing a similar role to ATProto, and a more diverse range of servers available for users to post on.

The catch with Bluesky or Mastodon is that it they are emerging frameworks: to get up to speed with using either (or developing on ATProto/ActivityPub) is more involved than traditional Web2.0 use. Still, it’s open and not too hard to work with. I’ve built a syndication script for this site, and found creating a client and making a post is straightforward. The development hurdles for LinkedIn, Reddit, or Twitter have all become more difficult (rate limiting, stricter auth requirements, and limited development programs etc.).

Cloudflare, AI, and paid access

If I look at the traffic for this site, it’s overwhelmingly from Ireland. Maybe I have a dedicated readership from there, but I think it’s much more likely that web crawlers accessing my site are hosted in data centres in Ireland (If I’m wrong, shout out to my Irish audience — you’re one of my favourite Eurovision countries). The rise in web crawler traffic driven by the proliferation of generative AI shapes the fundamental economics of running high traffic websites.

I pay pennies per month for hosting this site, but for higher traffic sites, this becomes as much of a cost/bandwidth issue as video was for RSS. If social media discovery killed ad revenue for news sites, the expansion of machines crawling their content will be even worse. Crawlers increase traffic, but don’t generate meaningful ad revenue.

And this is just the early days of machine driven interaction with sites. I don’t know whether “generative AI-powered browsers” will take off, but the idea is that generative AI-powered tools will browse the web for us, acting like an interface for the content posted on websites. They don’t look at ads, they don’t buy merchandise (or at least I don’t want AI doing that for me). They extract information and present it to readers in a way that is more focused than the noisy world of Web2. It’s natural to prefer the experience of a focused chain of messages with an LLM over the noisy clutter of Twitter or Facebook. It’s part of why I like RSS!

If the web is funded by ads and the “users” incurring costs ignore ads, the economic model collapses.

Enter HTTP:402: Payment Required (It’s an old idea!)

This is an old mostly unused web standard that companies are talking about reviving. The idea is simple. When a crawler hits your site, instead of blocking it, or showing ads that won’t reach a human, your server asks for a micro-payment. Basically it says “If you want to scrape this blog post to summarize it for a user, please pay me a $0.01”. This payment is transferred via a digital wallet, and the server delivers the content in a machine readable format (typically JSON/Markdown).

In a sense, this is an evolution of paid RSS. The idea is that my hosting service provides content to the consuming service for a fee, with no ad-tech middlemen. It’s being heavily discussed and implemented by providers like Cloudflare. Also, I could build an MCP for interacting with my site that includes rate limits and subscription requirements for access to my content. When an agent attempts to interface with the site through the MCP, they’re rejected without a subscription. The question really becomes one of scale, utility, and access.

There are difficulties and problems for this route, and there are risks of technological capture by providers like Cloudflare. It also leaves me wondering about whether this is closing off the old ideas of the open web, but we also have to navigate handling costs for hosting and creating content.

Summary

It has been an interesting historical moment. Not just because of the massive social and political upheavals that are going on, but because we’re reaching the breaking point of the Web 2.0 paradigm.

We’ve spent 20 years trying to fund the web with human attention and we ended up with a surveillance economy that feels unsustainable. I think the future consists of a mix of tools for discovery and paying for the content that you want to support or use, and I think we’ll see a mixture of self-funded projects supported by 402 payments for machine access, tokenized RSS feeds, and self-owned newsletter services.

If we’re drifting away from the fully open web, I’m okay with that. I’d much rather an honest, utility driven system of communication. We should give more power to creators and consumers of media, that preserves our attention.

And best of all, it’s going to be built on plumbing that works.*

Ok, there’s a lot of messy, competing protocols here and I’m being a little optimistic. But I do think that there’s a fighting chance for the internet at the moment.

Anil Dash: "How Markdown Took Over the World"

Mon, 12 Jan 2026 14:01:16 -0500

Markdown is pretty cool. It’s flexible, comes in different flavours, and it’s everywhere. Anil Dash goes into the history of markdown and blogging (and some of my problems with CMSes) in his latest post:

Because sometimes those writers would inspire us to make a new feature in the publishing tools, and sometimes they would have hacked up a new feature all by themselves in between typing up their new blog posts.

A really clear, and very simple, early example of how we learned that lesson was when we changed the size of the box that people used to type in just to create the posts on their sites. We made the box a little bit taller, mostly for aesthetic reasons. Within a few weeks, we’d found that posts on sites like Gawker had gotten longer, mostly because the box was bigger. This seems obvious now, years after we saw tweets get longer when Twitter expanded from 140 characters to 280 characters, but at the time this was a terrifying glimpse at how much power a couple of young product managers in a conference room in California would have over the media consumption of the entire world every time they made a seemingly-insignificant decision.

The other dirty little secret was, typing in the box in that old blogging app could be… pretty wonky sometimes. People who wanted to do normal things like include an image or link in their blog post, or even just make some text bold, often had to learn somewhat-obscure HTML formatting, memorizing the actual language that’s used to make web pages. Not everybody knew all the details of how to make pages that way, and if they made even one small mistake, sometimes they could break the whole design of their site. It made things feel very fraught every time a writer went to publish something new online, and got in the way of the increasingly-fast pace of sharing ideas now that social media was taking over the public conversation.

Anyways, there’s some interesting context with things I’ve been mulling over (for another blog post that I’m revising, but should be out soon), including Aaron Schwarz, RSS, podcasts, etc.

Dash’s entire post is a strong reminder that the literal skeleton that defines modern AI infrastructure, started as a conversation between a blogger and a teenager. Powerful tools are built for humans, by humans.

But I do think what’s really powerful is this section:

The people who make the real Internet and the real innovations also don’t look for ways to hurt the world around them, or the people around them. Sometimes, as in the case of Aaron, the world hurts them more than anyone should ever have to bear. I know not everybody cares that much about plain text files on the Internet; I will readily admit I am a huge nerd about this stuff in a way that maybe most normal people are not. But I do think everybody cares about some part of the wonderful stuff on the Internet in this way, and I want to fight to make sure that everybody can understand that it’s not just five terrible tycoons who built this shit. Real people did. Good people. I saw them do it.

The trillion-dollar AI industry’s system for controlling their most advanced platforms is a plain text format one guy made up for his blog and then bounced off of a 17-year-old kid before sharing it with the world for free. You’re welcome, Time Magazine’s people of the year, The Architects of AI. Their achievement is every bit as impressive as yours.

If you love the internet, the whole piece is an excellent read (including the 10 reasons markdown was successful). It’s also worth following John Gruber over at Daring Fireball.

Thoughts on Designing Automation

Mon, 12 Jan 2026 00:00:00 +0000

Automations are great. It’s pretty cool to explore building them. And it’s exhillarating when it works.

This is the appeal behind Factorio, a game entirely about building and optimizing supply chains. It’s addictive watching your expanding world of conveyor belts, resource extraction, and processing facilities. Building the POSSE script for this website has felt similar.

It’s easier than ever for workers in the knowledge economy to build automation into their workflows. As knowledge workers, we often build automations to save time, but without intentional design we inadvertently build systems that make demands on us. When you propose some kind of automation, people will respond to it based on how that system can be deployed in a context where it’s used to accelerate and coordinate work. This post is a call to consider the human element when we’re building and promoting automation.

I have no training in automation or design theory, but I think there’s two properties that can frame how we think of building automations: legibility and intrusion. I’ll talk about some design patterns along the way — trying to illustrate ways in which these features matter for human experience. And I’ll conclude with why this is important for our current moment: discussions about improving efficiency are dominated by tinkerers’ tunnel vision. Building things can be so exciting that we forget that we’re building systems and shaping practices and expectations for how we work.

Centaurs and reverse centaurs

Cory Doctorow has a helpful framing of automation in terms of centaurs and reverse centaurs. The basic idea is that some automations assist humans, and the experience of using them is empowering or thrilling. You function as a human head on a tireless machine body, and you’re able to do more, move more quickly. A reverse centaur is the opposite — a technology or system that demands (or controls) human inputs to produce optimized outputs. In this situation, the experience is reversed. You are dragged along, trying to keep up at the pace or quality of outputs that the system demands.

His most helpful example is in terms of assistive driving technologies. They can aid with driving more safely or efficiently (e.g., blind spot detection, cruise control). But they can also treat the driver as something to be measured and optimized, like monitoring a driver’s eyes and deducting points from their rating if the driver doesn’t pay attention on the road. On the reverse-centaur model, human effort is something to be modified by the system, while on the centaur model, the driver is augmented by the device.

These categories are about the relationship of the automation to the person. Is it aiding their tasks, or demanding and shaping their effort in a particular way? We can distill these models to two design patterns

Centaurs: An automation that lets you complete a task more quickly. It accelerates your velocity when working on tasks, you are a human augmented by the machine.
Reverse Centaurs: An automation where the machine treats human effort as a demand/input for accelerated output. It generates demands that users must conform to, and the human augments the system.

Design patterns are ways that automations can be shaped. One of the lessons from the assistive driving technology example is that this shape isn’t about the immediate things that the technology offers to users, but about the ways that they can be embedded in broader social systems. Part of the experience is about how automations treat the humans using them.

Legibility and intrusion

I think there are two key properties of automations that shape our experience with them. If I create a bash script, I’m immediately familiar with its logic and in full control of when it runs. If I’m working in Salesforce or a complex system of Zaps, I might be completely unfamiliar with the definitions and conditions of flows that generate notifications or tasks for me to complete. These examples differ in terms of the legibility of the automations and how intrusive they are for me. My script is extremely legible: I wrote and determined its logic. But it’s also intrusive: I have to run the script in my terminal. The background flows which send an email are the opposite: their logic is hidden and it’s minimally intrusive. I may not even be aware that someone is notified.

Here’s what I mean by these two terms:

Legibility: Can the user see the “Why” and the “How” behind the automation? Does the user have the ability to adjust those elements, or incorporate this into their approach for the task?
Intrusion: Does the system force a stop or change in the user’s path? Does it demand effort as an input before the output can proceed?

I want to stress that degree of control over the system is part of its legibility and intrusion is a measure of the effort and quality of how the system intrudes on a user’s experience or flow.

Here’s an example of legibility: A continuously variable transmission (CVT) in a car engine is low legibility and low intrusion. It transforms mechanical energy and simulates shifts, but you only need to put the car into drive before you stop thinking about it in operation. It is background mechanical infrastructure. A bicycle’s gearing system is both high legibility (you can literally see the parts) and higher intrusion (users must select the gear), even though it has a similar function. It feels like a tool that you need to use and efficient use requires “how-to” knowledge. Both systems are empowering — they enable users to effectively transform mechanical energy. Where they differ is in terms of legibility.

For a system to be centaur-like, the intrusiveness of the system must function in a way that’s engineered to empower the user. Low intrusion systems are more likely to be centaur-like. Cruise control eliminates the cognitive load for managing your velocity. Blind-spot assist is intrusive in a way that prevents drivers from making errors of judgment. Driver rating systems are intrusive in a way that allows managers/insurance companies to use incentives to encourage conformance. The scores and their impact on employment/prices are intrusive in much deeper ways than a blind-spot alert and they are often low legibility (especially with regard to how and what is being monitored). Reverse-centaurs are organized in a way that structures the end result without regard for how people enter into the system.

We can think about this in terms of a two by two matrix:

	Low Legibility	High Legibility
Low Intrusion	Background infrastructure. Background processes that just work.	Assistive Aids. Systems that provide signal, adjust outputs, etc. without force or effort.
High Intrusion	Reverse-centaurs. Systems that demand increased outputs or compliance with opaque rules.	Tools, Frameworks. Systems that require effort but offer control and clear insight into their logic.

If a system is highly intrusive but low legibility, it feels like a demand. If it’s high intrusion with high legibility (like the bike gears), it can feel like a tool or framework. The difference is whether the user understands the ‘why’ behind the friction. If it’s low legibility and low intrusion, it feels like background infrastructure. If it’s high legibility and low intrusion it feels like an aid. Fundamentally, reverse-centaurs are lower legibility, high intrusion — when an automation demands a higher standard or an accelerated pace of work, that harms its legibility. Centaurs can occupy a range of other spaces: but most often, they’re high legibility and low intrusion.

Types of automation

If we think of work as getting a bunch of tasks to be done with specific outputs, we can begin to think of automations as things that help us identify tasks, schedule and perform those tasks, clean-up after tasks, and alert us to when things are done. The ways we build and design these things can vary in the legibility/intrusion dimensions.

In this model, there are two fundamental types of automation:

Gates: Prevent work from going out unless they meet some kind of condition or standard, they can also prevent the reverse centaurs from swamping you. They can also filter or limit inputs into the work process. Gates provide prevention and control. Gates range in intrusiveness and legibility, but generate intrusion.
Cogs: Work inside of a machine, smoothing out friction without intruding on the user experience directly. They can transform energy, change a thing, or generate new output. Cogs are the engine that maintains velocity or acceleration. Typically, cogs are lower intrusion, and range in legibility.

These are similar to the basic elements of a programming language: functions and control statements. You can build arrangements of gates and cogs to perform more complex functions. Bash, Python, Salesforce Flows, n8n, are all pretty much the same in this respect. As design patterns, they are the basic atoms that let us build more complex systems.

Some of the more complex systems include:

Sentinels: Put a cog after a gate so that something happens when a condition is met. The basic idea behind this is a notification system. Sentinels provide warnings. They may or may not prevent the machine from running off course. If the end goal of a sentinel is adjusting human behaviour, it’s higher intrusion.
Gardeners: Run on a schedule or condition to delete, prune, archive, or organize. They prevent cogs and reverse-centaurs from overwhelming you (a script that cleans up my screenshots). Think pruning shears. They might have moderate to high legibility, but lower intrusion.
Bridges: Transform information, data, tasks, or other inputs between forms. (Pandoc or ETL scripting). Typically lower intrusion and variable legibility.
Distillers: Take a feed or stream of information and provide summaries that are useful for users. Reports and dashboards are the main examples. They extract signals from noise. Low intrusion, high legibility.
Squires: Perform set up before you start a task. Package managers, tools to create virtual environments environments, etc. Typically lower intrusion, high legibility.

These aren’t exhaustive, but I think they’re helpful for getting an idea of how far this metaphor can run. One thing that’s important is that these metaphors all have an element of responsibility — this comes from the idea of the task having a functional goal. In my own approach to docs-as-code, I have distillers (spellcheck, Vale), gardeners, sentinels, and squires squished into a build and deploy script, and the static site generator functions as a bridge between markdown and published HTML.

Here’s the thing I’m going to argue for in this post. We can build automations out of gates and cogs, it tells us nothing about where we fall on the centaur/reverse-centaur axis. This is because I believe that technology has a fundamentally social aspect to it — technology (including automations) requires that we coordinate and prescribe tasks between human beings.

We often think about building automations in isolation. There is a task that I’m doing and the automation I’ve created eliminates performing that task for myself. Since it accelerates what I’m doing, it’s exciting and good. This is what I’m calling tinkerer’s tunnel vision. It can lead to a range of results, some good, some bad. Let’s use Vale as an example.

Implementing Vale

Vale uses syntactic pattern matching to check whether HTML or markdown conforms to a style guide. You can define and extend sets of rules and check for things like passive voice, common misspellings or typographic errors, and whether or not you’ve used title case or sentence case for headings. It’s catnip for technical writers who want to ensure that their articles meet certain quality standards and are happiest working in a docs-as-code environment. You can tinker with regex to generate suggestions, warnings, and errors.

It can be run in the command line and a really common way of using it is as a gate. As part of the process for deploying your site, you require that a branch passes the relevant checks. You can also run the command whenever you work on a file in your command line interface. And there’s an extension for VS Code that gives you live feedback as you work.

Is it a tool that makes you a centaur or a reverse-centaur? Well, that depends. Though I think it largely feels like a centaur. Consider these three ways you can use Vale:

The empowered contributor. Vale is implemented as a CI/CD gate and the writer is able to use the VS Code extension while they work to get live feedback as they write. It will be rare that they submit any pull requests to be merged with style guide violations since it’s available both as a final check and as an assistive tool.
The demanding oracle. Contributors may be aware of the style guide, but they are responsible for meeting the Vale check, but they are not provided the relevant style files or assistive tools aside from the CI/CD check, and instead must adapt their behaviour to conform to the style guide based on their ability to learn the system.
The sorcerer’s apprentice. An automation is set up that generates Jira tickets based on Vale output. We set up a new style guide, and run the script for every page on our site. This generates a massive backlog of content that must be brought into alignment with the new style guide.

The demanding oracle isn’t a good way to implement the tool: it’s a fundamentally flawed approach to developer experience or a culture of trust. It isn’t a good experience precisely because of how the social organization around the tool is structured. That is, the demanding oracle is a perfect example of how a gate with low legibility functions as a reverse centaur demanding quality. Similarly, if you implement Vale in the manner of the sorcerer’s apprentice, it is a sentinel with high intrusion. Without a policy and plan for how to pace work through the backlog, this implementation quickly becomes a reverse centaur demanding quantity.

In the empowered contributor model, writers have access to the tool as an assistive technology and as a quality control gate on the final product. They know the standards and have distillers in their authoring process guiding them on how to meet those standards. And they determine the pace of their output. This becomes more centaur-like.

Interestingly, part of why skilled writers are valuable is precisely because of their ability to write about the subject matter and within constraints about the quality of their output. Good judgment for writers involves internalizing this knowledge and having a practice that enables them to achieve the level of output. Being that sort of writer involves dedicated practice and expertise, knowledge of how to use assistive technologies to produce quality docs is valuable. In a model where the legibility of Vale isn’t equally distributed, we might have increased demand for labour that can meet the quality standards.

Implementing Vale also imposes a new layer of work. Maintaining and updating the style guide is something that needs to be done. Adding Vale to the CI/CD and maintaining the CI/CD flow is something that requires work. Coordinating new style guide rules and propagating that knowledge to marketing or comms teams is also social work. Automated tooling can elevate the standards and quality of your work, but these things are embedded in a larger context of effort.

Whether or not we perceive Vale as a centaur or reverse centaur fundamentally depends on legibility and intrusion. And these things are fundamentally about how a human being perceives and works with the automation. It’s about arrangements of cogs and gates in ways that help, hinder, intrude, and expedite work.

The human element of automation

So! When we discuss automation, you might wonder why people don’t respond as favorably to some approaches as others. I think this is often because of the fact that something that might be empowering for one model of work might be demanding for another.

What I take from the Vale example is that we can view this kind of disagreement as arising from how your proposed automation treats people. Think about whether that person is being treated as a disposable element of the machine or being protected or empowered by an arrangement of cogs, distillers, gates, and sentinels. Are they visible? Intrusive? Where is friction generated by the demands of the system? What is the person left to do in your system?

A system that only produces outputs to be validated treats the user as legs for the reverse-centaur. A system that helps you develop quality work and leaves you to exercise your judgment at key choice points is one that treats the user as a centaur. It’s easy to have a solipsistic view of the tools that you develop for yourself, but working in software is a communal effort. When we deploy an automation, whether we’re a consultant, individual contributor, or a manager, we’re coordinating tasks and trying to ensure quality of outputs.

What might seem like an empowering assistive tool to one individual could leave another individual at the whims of a demanding oracle. The same assistive technologies that enable me to drive more safely, when plugged into a system of labour relations and measurement, can require the Amazon driver to have to perform at a level that’s beyond their human endurance.

Ursula Franklin’s notion of prescriptive technologies (from The Real World and Technology) is helpful here, which she defines as:

…specialization by process […] Here, the making or doing of something is broken down into clearly identifiable steps. Each step is carried out by a separate worker, or group of workers, who need to be familiar only with the skills of performing that one step. (20)

Prescriptive technologies are means of coordination, and they require that individuals comply with a standard or process in the course of producing output:

…the process itself has to be prescribed with sufficient precision to make each step fit into the preceding and the following steps. Only in that manner can the final product be satisfactory. The work is orchestrated like a piece of music — it needs the competence of the instrumentalists, but it also needs strict adherence to the score in order to let the final piece sound like music. Prescriptive technologies constitute a major social invention. In political terms, prescriptive technologies are designs for compliance. (23)

Demanding oracles, then, are a kind of prescriptive technology that lacks legibility. Working with a standard that is opaque, or not legible, is frustrating. It’s even more reverse-centaur-like if we build sorcerer’s apprentice scenarios where the system demands increased effort in terms of quantity, without regard for the current state of the system.

I want to caution us from concluding that prescriptive technologies are inherently wrong. Style guides are a perfect example of a prescriptive technology. They are tools for making the writing of groups of people look like it was written by a single person: coordinating human effort to produce a uniform quality of output. By using Vale as a gate and distiller we empower users to meet a higher quality of output.

Software automation fits a range of design patterns. Franklin defines holistic technologies as being associated with craft — allowing skilled workers to have control over their work from start to finish. But useful tools for craftspeople can easily become prescriptive standards for those who want to coordinate labour. And coordination is important when communal effort for single outputs are required. We don’t get to build software, airplanes, buildings, etc. without coordination. When we have powerful holistic technologies, it’s very easy to get into tinkerer’s tunnel vision: we get focused on the power of the cool systems of cogs and gates we can build. Being a skilled craftsperson, piloting a centaur, it feels good.

I think this does more to expalin the gap between adopters and resisters. It’s very easy to use generative AI to build an automation: typically, generative AI is low legibility and high intrusion. The internal logic of the chatbot is masked, but we can treat it as a gate, cog or source of tasks. If a writer or programmer has to review mountains of AI generated output, it feels like something has gone wrong. But for some ways of working, this is a success. Since the implementations, expectations, and use cases aren’t uniform, the conversations break down.

We’re in a social moment where people expect generative AI to accelerate the output of work. I hope that I’ve demonstrated that automations in the workplace involve both machines, people, and systems of coordination. I didn’t mention LLMs, generative AI, or agents until this section, because in a way, this isn’t a problem unique to artificial intelligence systems in 2026 — the issues are fundamentally about system design.

System design is something that often occurs organically or top-down at organizations and individual contributors often have little agency over the systems they find themselves in. Generative artificial intelligence provides a range of implementation possibilities, some of which are low legibility and high intrusion, but we don’t have to design systems like this. The intern model adopted in copilots and assistive technologies increases the legibility to operators and moderates the intrusion. Agents — construed as markdown files governing contributions to a codebase from an LLM — reduce intrusion (for operators) and moderate the legibility (for operators). The extent to which we build sorcerer’s apprentice or demanding oracle situations for ourselves is a matter of design and management.

When you’re excitedly talking about the automation that you’ve built, consider whether it is treating people as pilots or as gears that need to keep pace with an accelerated system. The experience of being empowered to make your own choices as a craftsperson is different from having an increased backlog of automatically generated PRs to review.

If we fundamentally view promoting automation and efficiency gains in terms of systems of trust, responsibility, and coordination, we can build better tools, cultures, and results as technologists. By building systems in the lens of “squires” and “gardeners” instead of “demanding oracles” we can build cultures of craft, which seems like a better way to work.

Drew Bruenig: "Why I Write"

Tue, 06 Jan 2026 15:22:16 -0500

Here’s a really nice piece from Drew Bruenig about why you should write. These reasons are definitely part of why I’m writing this blog (and why I link blog). It’s also why I’m happy to see more technical writers joining the technical writing webring.

I think writing is one of the most valuable things you can do, and I recommend everyone try it. Here’s why:

It makes you a better thinker and communicator. Writing is a muscle. The more you write, the easier it gets, and your ability improves. You’ll learn to make clearer arguments, crisper explanations, and better empathize with your audience. These skills are applicable to everything.

You’ll get feedback that makes you a better writer. Feedback exposes weak arguments and strengthens the good ones. Plus, learning to listen to feedback is another skill that is universally applicable.

You’ll meet people interested in the same things you are. Looking through my correspondence, it’s amazing how many of my favorite people to chat with I met through writing online. (BTW, this goes both ways. If you read something that resonates with you online, write them a note thanking them and telling them what you liked!)

Your past thinking will be archived and searchable. This is more valuable than you think. If you invest time to hone a piece, you’ll turn back to it more often than you’d expect. Further, reviewing old pieces and threads over time will reveal what worked and what didn’t while making your progress tangible.

The value of your writing compounds. The value to you, that is. I don’t think my pieces from 6 years ago are improving anyone’s life, but the contacts I’ve made and pieces I’ve crafted have grown into a foundation I get to leverage everyday.

Writing gives you a license to explore and organize your thoughts. This is the fun bit. Chasing down an idea that interests you, forming questions and then investigating them; it’s a joy. The second most common question I get about my writing is, “How do you motivate yourself to write?” This is the answer. There are so many drafts that live, dormant in my draft folder. So many times I start a piece and lose interest. And then: something will click and I’ll draft, investigate, and finish a piece in an hour (here’s two examples). These aren’t always the most substantive pieces, but they keep the practice going and the momentum up.

But I think this really a key part of doing blogging:

Be okay with bad writing. Most writing isn’t great! If my hit rate is 1 out of 5, I’m thrilled. Get comfortable publishing things that aren’t perfect. I know many people who wait too long to publish and, well, never do. They do this for years. If they’d gotten the ball rolling back then, they’d be better writers today. It’s weird: you’d think regular private writing would be sufficient to get better. But it isn’t. There’s no stakes. No feedback. The only way to get better is to ship. Some people worry about the risk of bad writing. I think the biggest risk comes from being an asshole (so don’t be an asshole!) But the actual risks are quite low: most bad writing is neutral, it remains unread.

One thing I struggle with is keeping my posts simple and short. If you have a similar perspective, I’d consider giving link blogging a try. It helps you build the habit and stay engaged with your blog. It also encourages me to read in an engaged way and take notes about what I’m reading. Also! I think reading is a key way to build writing skills. Find writers you enjoy and see how they approach writing a blog post (or book, newsletter or whatever!). The main point is to build the muscle and find what works for you.

My Guidelines for Writing About AI

Tue, 06 Jan 2026 00:00:00 +0000

Writing about AI was hard.

I was once a TA for a philosophy course where students were encouraged to write about AI, back before the advent of ChatGPT and generative AI. It was difficult giving feedback even when navigating a reading list I was familiar with — students came from a range of backgrounds in philosophy, cognitive science, computer science, etc. I’m glad I’m not TAing for the same course now, since writing about AI feels even harder these days, for a variety of reasons.

To be honest, I feel kind of paralyzed when trying to write about AI. It’s incredibly easy to mean one thing, be heard saying another, and accidentally trigger a conflict you didn’t intend. I’ve been thinking about principles that could guide how I blog about generative AI in a way that’s responsible and precise.

The problems

The biggest reason for this linguistic minefield is that “AI” is a shortcut for a range of phenomena that are better discussed with more precise terms.

If I write a blog post about “AI” today, I could mean:

The general concept of human-like machine intelligence.
Generative AI, by which I mean the broader space of tools using machine learning techniques to generate text, audio, images, and video.
Specific apps like ChatGPT, Gemini, Claude, etc.
Specific technologies behind the apps, like LLMs and system prompts, transformer architecture, etc.
Specific applications of these apps for productivity.
Machine learning applications that used complicated statistics to determine models of phenomena that have nothing to do with general purpose computing.

The ambiguity gets even worse when you use general summary verbs. Think about the multiple meanings that could come into play for the phrase “using AI”: If I tell a junior writer they should learn to use AI, do I mean that they should interact with a chatbot during the writing process? Learn how to create scripts and tooling to enhance their workflows? Learn how to create entire drafts through prompts? Learn how to use Code Wiki instead of talk with developers? The verb “use” is incredibly ambiguous, on top of the ambiguity of “AI”.

The ambiguity in these discussions is a mile wide and deep. And it makes it very easy for two people to think they are arguing about values when they aren’t even agreeing about the meaning of the words. Things that might look neutral are incredibly value laden: “productivity”, “quality”, “ownership” are all tied to worth in various ways in western culture and internalized by individuals. A remark about what is the most productive way of doing something or what someone should do quickly becomes an evaluation of worth.

And the problem compounds as our brains are primed for confirmation bias, political allegiances, and internalized norms. I’m not immune to this. I don’t think there’s an actual view from nowhere that we can occupy. So, for me at least, writing about AI is like navigating a linguistic minefield.

My goals

Here’s something I remarked in conversation with other technical writers regarding writing about AI:

I’ve struggled with writing about it [AI] too. I want to stake out a “aware, cautious, and critical” space. But this kind of writing is just extremely difficult, since the broader space is heavily value-laden.

If you say “I use it to write scripts to enhance my productivity”, that reads as whole hearted endorsement, since we occupy a professional world that values productivity. The reality is leadership expects us [technical writers] to ship faster because of these tools (that’s what they were sold after all!). We should have a good response (“I can do x, y, and z. But u, v, and w are productivity theatre. Here’s my evidence.”), and that involves engaging with the tools so we can discern what is what.

And I fully acknowledge that in some way, playing this game (writing about how AI can be used) normalizes the political, ethical, ecological, and economic frameworks that make this technology so controversial. But at the end of the day, this is a complicated collective action problem, and the technology is here, along with leadership has expectations about how it should change my workflows.

As someone who works in software, this is a conversation that’s happening around me, so I should participate. If my employers expect me to be aware of how I can use these things, I should be engaging with those things.

And I’m someone who has a deep drive for clarity driven by a career in philosophy and strives to be a critically engaged lover of technology. Isolating ideas is something that comes naturally to me. I love the things we can do with computers. But I also want to be sensitive to questions of the value of human labour and creativity. So I try to be aware of a wide range of perspectives on AI. I found this post on AI skepticism really helpful for identifying different ways of thinking and writing about generative AI. My goals are to be aware of what I’m saying and how others might take it. To be precise and informed in a way that avoids conflict where I don’t intend it. Essentially, I really want to fall close to the informed critics part of this group — and enjoy reading posts by folks like Simon Willison, Colin Fraser, and Drew Bruenig.

Why personal guidelines?

Ok, because of all this difficulty in the language surrounding AI, it makes the topic intimidating to write about. And I enjoy blogging and thinking about technology. By formalizing my feelings and thoughts into a set of principles and guidelines, I can assess my own writing and check myself before posting things. Basically, this is a personal style-guide for blogging about AI.

This isn’t a hard and fast set of rules for everyone. If it doesn’t work for you, that’s fine. And the technology will change, so I’m sure these guidelines will have to adapt as well.

Each point is an imperative. They’re reminders of what I need to do to achieve the goal that I laid out in the first section: avoid confusion and harm, prioritize accuracy, and remember that this topic is heavily laden with values and norms.

My personal guidelines

These ten guidelines are how I want to approach writing about AI. Each point includes a bit of explanation:

Be as specific as practicable. If a more specific term can be substituted into my sentence, use that term instead of AI. If I’m really talking about an LLM, then I shouldn’t use AI or even generative AI. If I’m talking about an app or a specific feature, I should say that instead of the LLM. Grok is a feature in Twitter/X and there is a model Grok 4.1, Gemini is an app but Gemini 3 Flash is a model.
Watch your verbs and pronouns. Avoid anthropomorphizing AI by employing verbs as a shortcut. Avoid “the AI thinks”, “understands”, “knows”, “decides”, “hallucinated”. Use “the model calculates”, “predicts”, “outputs” or “processes”. This is doubly true for pronouns. Using personal pronouns (“you”) for these things is part of the illusion that we need to resist.
Remember humans read your writing. People are primed for polarization. Both for and against and that includes myself. Readers arrive with pre-existing fears of job loss or hype fueled optimism. Regardless of my intent, writing about AI means trying to navigate an explosive minefield. Be humble and own up to errors.
Remember your audience. Don’t assume that other people have similar pressures on how they interact with, or understand, technology. As a technologist, I have curiosity and a professional responsibility to be aware of how the technology works that other people don’t. When I write about it, I may need to spend more words to get them on the same page. As a recovering philosopher, I have been trained to be painfully clear in a way that people might find frustrating.
Be aware of background values. Saying that AI enhances productivity is a value laden statement, or is easy to interpret as value laden given our culture of capitalism. Being neutral is difficult and I should be cautious about the normative aspects of what I’m writing.
Be aware of background injury. I don’t depend on the value of my intellectual property for my livelihood as much as other professionals. A photographer or illustrator has a different relationship to content scraping, which can be a direct harm.
Center the human operator. It’s easy to omit people from the picture if AI is an automation, but people are ultimately responsible for the automations they create, the outputs they accept, and the affordances a feature provides. For example, “The summary is generated by the AI” is passive, “The AI summarizes the text” attributes agency to the AI, and “I used the app to generate a draft summary” centers the operator (it also reinforces that the app is used instead of the model!).
Remember the parts that make the whole. In generative AI, many components are presented as a simple thing. Awareness of those parts helps build clarity. The model is a complex blob of linear algebra. The system prompt mediates interaction with the model. The chatbot app is filtered by additional prompts and context. Web search is a separate component from the model. The UX conspires to hide these things. Clarity is important and difficult, but valuable.
Remember your perspective. I don’t have the skills or knowledge to assess every aspect of generative AI, let alone AI. I can contribute to a conversation as one voice, with my perspective. Other people have other skills and knowledge, and I should strive to be charitable in interpreting their perspective.
Demand clarity, but be open to generalizations. Communication is hard. We use lossy abstractions to quickly convey ideas. It’s important to get on the same page, but remember that others may have deeper or shallower understanding of the same topic.

I’m not sure if these guidelines will satisfy everyone. But I know that these guidelines keep me from off the cuff posting about what’s a sensitive and difficult topic. We’re all in this together and trying to figure it out. I plan on posting a short series of posts about AI and the technical writing profession in 2026, so getting these principles out here is an important part of framing what I’m trying to achieve.

One last note: It’s important to distinguish between writing about AI and the act of documenting AI products. The latter is a specific technical challenge where the architecture of the product dictates the shape of the writing. Documenting a foundational model (focusing on context windows and tokenization) is fundamentally different from documenting an MCP (Model Context Protocol) implementation, an agentic workflow, or a simple AI-powered feature. Each of these “products” requires a different level of abstraction and has different audiences with different backgrounds and needs. While these guidelines help me stay responsible when blogging, they are the foundation for the precision required when I’m actually in the trenches documenting these distinct architectures.

POSSE for Hugo: Part Two - The Product

Fri, 12 Dec 2025 00:00:00 +0000

In my previous post, I explained the theory behind the Publish on your Own Site, Syndicate Elsewhere (POSSE) script I’ve been working on for this blog. POSSE is a strategy for managing and distributing your writing. Since this Hugo site is my home base on the web, adding an automated syndication script would be a fun and powerful project.

Here’s a public repository for the script on Github: hugo-posse

It’s available under the MIT license, and free for anyone to use or modify. The plan for this post is to talk about how I use it with my site, and what’s next for improving this site.

Setup and configuration

For this site, posse.py lives in the top level of the project directory along with some other helper Python scripts. This is the easiest way for me to call them, whether they help backup images or build and deploy the site. The README includes detailed installation instructions.

The script relies on several libraries, most notably atproto and mastodon.py, so these are included in a requirements.txt file. You can use pip and this file to quickly install these libraries.

To securely store your credentials, I’ve opted to include a .env file in the root of my Hugo site project. My site configuration is stored in Github, which means it isn’t suitable for holding keys or passwords. I instruct Git to ignore this file (in my .gitignore). If you plan on using this script, I highly recommend doing the same.

The most complicated part of setting this up is getting credentials from Bluesky and Mastodon, but this is well documented in the scripts README file.

Testing

Honestly, coding with Gemini as an assistant made this go very quickly. I have some Python knowledge, so basically this was “centaur-like” development, where I had a very effective intern pushing this project to completion. With a bit of the planning in place, I was able to use Gemini to come up with strategies for handling TOML/YAML pretty easily along with loops and structures to handle leaf bundles vs. individual files in the parsing and execution logic.

I wanted to include the ability to do a dry-run before actual runs, which is flagged through the --dry-run argument.

The one unexpected element was a compatibility conflict between atproto and Pydantic. When I ran tests I’d get a blob of warning text:

...\pydantic\_internal\_generate_schema.py:2249: UnsupportedFieldAttributeWarning: The 'default' attribute with value None was provided to the `Field()` function, which has no effect in the context it was used. 'default' is field-specific metadata, and can only be attached to a model field using `Annotated` metadata or by assignment. This may have happened because an `Annotated` type alias using the `type` statement was used, or if the `Field()` function was attached to a single member of a union type.
  warnings.warn(

This warning doesn’t have any effect on the finished script, so I’ve decided to suppress this in the import block for script. This is a bit of technical debt, which I’ll keep in a note in Obsidian for maintenance for this project.

Also, in order for this to work, you have to have strong markdown file hygiene. An extra hard return at the start of the file can result in the parser skipping the file. But the way it’s structured is that it detects front matter at line one of the site. Better parsing is also in the list of to-dos for this project.

The workflow

Ok! So the workflow is pretty simple. The goal is to make syndication feel like writing, not like managing or repeatedly copy and pasting everywhere.Here’s how this plays out in writing:

When I draft my Hugo content, I can decide whether I want to syndicate the post. If I do, I add two standard elements to the front matter for that post: syndicate_to (a list of strings for syndication targets) and microblog_content (the post for Bluesky/Mastodon). If I don’t want to syndicate the content, I don’t. In the microblog_content field, I add a summary of what I say in the blog post and a couple of hashtags.

There’s nothing that ties me to writing inside of the social media apps, which lets me stay focused on finishing a quality blog post, without the noise and distraction of social media.

When I’m ready to publish, I go through my build/deploy process. I’ve decided to automate that, but for manually building and deploying my Hugo blog, it looks like this:

rm -r -fo public
hugo build
gsutil -m rsync -r -n public gs://example-project

Then I wait a bit for the changes to hit my site, followed by running:

python posse.py content/blog --dry-run

Here’s the result of doing a dry run with a single post ready to syndicate:

This lets me preview the manifest and actions that the script would perform. If I’m happy, I run:

python posse.py content/blog

And here’s the successful feedback:

Since there’s a check on the syndicated: true boolean flag first, I don’t have to worry about posting duplicate content. After syndicating a post, the script will automatically add syndicated: true to the post. Between the --dry-run argument and the syndicated: true check, I really tried to prioritize security over spamming my social media feeds.

Minding the gap

There’s one problem I have with this approach and my stack of Hugo > Google Cloud Services Bucket > Cloudflare (for DNS/HTTPS/caching). I alluded to it in my first post: if I run posse.py too soon, the posts won’t be live, and the script aborts syndication. This is a condition where two processes are in a race to complete.

I came up with three solutions for handling this race condition:

Manually wait before executing the script.
Add this to a build/deploy script and use sleep 30 command to try and let my deployment finish.
Write a small loop to poll the URL on small intervals until I can syndicate.

I talked about manually working through the commands in the previous section, but here’s how the build/deploy script and sleep would work as a bash script:

# 1. Clean and build
rm -rf public
hugo --minify

# 2. Sync to GCS
gsutil -m rsync -r -d public gs://example-project

# 3. The pause
echo "Waiting 30 seconds for Cloudflare propagation..."
sleep 30

# 4. Attempt to syndicate
python posse.py content/blog

I’m toying around with a Python script handling build and deploy operations (apologies if I’ve accidentally doubled posts in your RSS reader). The thought is it can pull together some of my other utilities written in Python (like a script which backs up screenshots, since I don’t store them in Github) into a build, deploy, syndicate, and clean-up process.

Here’s how a polling loop would look in Python:

#Other libraries
import time
import requests

#Other methods

def check_url_with_retry(url, max_retries=5, delay=10):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, timeout=5)
            if response.status_code == 200:
                return True
            print(f"URL not ready ({response.status_code}). Retrying in {delay}s...")
        except requests.RequestException:
            print(f"Connection error. Retrying in {delay}s...")
        
        time.sleep(delay)
    return False

# Main execution loop:
if not check_url_with_retry(url):
    logging.error(f"Skipping {title}: URL not accessible after retries.")
    continue

Future directions

As I’ve gone through this, I’ve been keeping note of various improvements that I can make for the script:

My first test turned up something I missed during my Bluesky research, namely how Bluesky handles hashtags. Bluesky requires hashtags to be parsed and added as metadata when creating a post. On Mastodon, hashtags are plain text. Adding a separate method to parse and extract hashtags for Bluesky is a high-priority fix for now.
Better handling for parsing front matter (cf. the issue with a hard return before the front matter).
Writing links to Mastodon and Bluesky back into the front matter for the post.
Hugo is one SSG among others, I’m not sure about compatibility. But it might be fun to modify or extend this script to support other blogging platforms. The biggest barrier is that I’ve hardcoded the content folder structure into this script. It might not be too big of a lift to make that an argument for the script, but I’ve got some ideas to work around this.
Posts without linking back to this site — This gets me really close to using this site as a headless content management system for my social media. The idea is to add a folder to my Hugo project where I can write a short post, and syndicate that to the microblogging services, without publishing the post to the website and linking back to it. This Hugo site becomes my authoring environment for social media posts.
Obsidian is a note taking app that I enjoy using. It has a similar structure to Hugo (file directory of markdown files with front matter) If I support posts without linking back to this site, this is a very cool extension of the idea outside of blogging and into note-taking. You could use Obsidian as a weird headless CMS for social media.
Expanding to other social media platforms. If I’m really all about this site as a headless CMS for all my professional social media, then LinkedIn is a natural next step. So is Twitter/X.

While I want to get back on my writing, I’ll probably work through these issues and continue to blog about developing and improving this script. Maybe I’ll even have to rename the repository if I go far enough down the “SSG agnostic” route.

Conclusion

This has been a surprisingly fun rabbit hole to go down.

It combines practical coding with trying to find a better way to use the internet, built around my needs for writing and focus. If you’re feeling like you don’t have a lot of agency when it comes to your publishing pipeline, I hope this inspires you to try and build something similar. I can retain my focus while writing and easily share my content with more people (RSS, Bluesky, and Mastodon are all ways to follow this blog). While I don’t think I’ll syndicate shorter link blog posts, I’m excited to share more of my original pieces.

I’ve been balancing working on this with several ideas for long-form content for this blog. But I really wanted to get all this working before I started making those posts. There was a bit of back and forth as I got more into those ideas. But I’m glad this is in a usable and sharable state.

Expect a flurry of content before the end of the year. I’ve got some really interesting ideas about AI and automation for technical writers simmering on the back burner. After I clear that backlog, I’ll probably gravitate back towards a balance of link blogging content, long form posts, and technical projects that feels sustainable and aligns with my mood. If you’re reading this on social media, let me know what you’d be most interested in.

But I’m enjoying what this site is becoming and looking forward to continuing to blog and build it outwards.

POSSE for Hugo: Part One - Theory

Thu, 11 Dec 2025 00:00:00 +0000

I like the IndieWeb; it’s an idea and emerging set of standards for how to build independent websites that can talk to one another. I’m gradually building this website towards that ideal. One of the underlying ideas is POSSE (Publish on your Own Site, Syndicate Elsewhere) or COPE (Create Once, Post Everywhere).

The basic idea behind POSSE is that content should be posted to my own site first then syndicated elsewhere, with links connecting back to my original post. Why do I prefer this approach?

My site already does some syndication: I have an RSS feed for my blog, which is a stripped down feed of my posts. You can use a dedicated app (RSS reader) to subscribe to that feed. Your app will regularly check my site for new posts and present them to you without you having to come here. RSS does syndication brilliantly, but it has its limitations: for example, you have to know about the existence of the feed and use an app to subscribe.

Social media sites are a great environment for sharing and interacting with other users. You contribute to shared feeds of content, and can share posts to people connected with you. If RSS is one-to-many communication, social media is many-to-many. The problem with traditional social media is that you end up locked in. You can request your post data from Facebook or LinkedIn, but you’ll end up with a massive JSON file that’s unwieldy to use. By syndicating content from my site to social media, I can write in a central place and share my thoughts and ideas in community spaces. I own the content, in a format I can work with, and can take it anywhere. It’s backed up on Github and my hard drives. It’s a way of treating my writing as something I own.

POSSE is a practice, so you could do it manually. But, if I plan on syndicating the same post to Mastodon, Bluesky, Twitter/X, and LinkedIn, I would be adjusting a summary and pasting links into forms on each social media site. And if you repeat the same step enough times, it looks like an opportunity to automate with a script.

This post is a write-up of the ideas behind the script. The process was a little more creative and messy, working with docs and LLM assistants to build out something that met my needs. I’ll talk about the final script and using it in my next post in this series.

Targets, tools, and research

This site is built using Hugo. Hugo is a static site generator, and it builds HTML from markdown files stored locally on my computer (version controlled with Git/GitHub). Information about the post (metadata) is stored as front matter: YAML or TOML before the markdown content. The front matter can include labels, descriptions, whether the post is a draft, etc. Some of these terms are reserved by Hugo, but you can define other kinds of metadata. So I’ll create a post, with metadata, and build the website using the post metadata.

I’ve used various scripts to take care of various command line checks, cleanups, and repeated commands for working with markdown and this site. After I build the site, I use the command-line to deploy it to my hosting service.

The POSSE script runs after I build and deploy this site to syndicate the content. I decided to focus in particular on micro-blogging social networks, so I will author a single short summary or description for the post (including hashtags). By keeping the post close to the blogpost, I can write the “tweet”/“skeet”/“toot” as I write and publish new blog posts.

Aside: Mentions (using the @ symbol) pose a wrinkle that I don’t want to tackle at this early stage. Especially in federated services, where a Mastodon handle is different from a Bluesky handle. The easiest way is to log in and leverage mentions directly.

Here’s the core logic for the script:

Scan a directory of content from my site for posts that I want to syndicate.
If a post contains appropriate front matter (character length, whether I want to syndicate the post), add the post to a manifest (dictionary or list) of things to syndicate, and reconstruct the URL for the equivalent post (each entry is a post + link).
Verify that manifest links are live on my hosting service (ping the URL, receive a 200 OK response).
Create a session with the target service(s).
Send posts to those services including a link to my original content.
Update the front matter to prevent the script from posting the same content multiple times.

For now, I’m only to targeting federated social media: Bluesky and Mastodon. Why these two services? They’re the easiest to interact with via scripts. Twitter/X’s API is significantly more locked down than it used to be. LinkedIn has a very different kind of post structure that performs better and I don’t really want to deal with managing OAuth (yet). But ATProto and ActivityPub are open standards for developing and working with social media. The more closed ecosystems could be future goals for this project.

Implementation considerations

Here are a couple of technical considerations I had to keep in mind:

Since I use Cloudflare, there’s a time gap between running the commands that deploy my site, and the content becoming available. I have to account for this when I run the script or combining the build, deploy, and syndicate steps into a larger script.

If you’re really gung-ho about CI/CD, then there’s ways of doing this via GitHub Actions or Hugo Pipes. This feels like over-engineering for this site. The difference between merging a branch and running my build/deploy scripts locally is negligible for me.
Dependency management was another factor. Since I script in the most recent version of Python (3.13.2), I needed to be mindful of potential library conflicts or version mismatches in the environment.
To securely handle keys and other credentials, I needed to be mindful of my Hugo site structure and Github. Rather than store these keys in my site configuration, the script uses a .env file, which I explicitly tell Git to ignore.
Hugo uses the base URL for your site, individual markdown file names, leaf bundles, and metadata to set the URL of pages. I needed to accommodate this as well.

Bluesky

I’ve talked a little bit about learning about ATProto in the past, which is the protocol that Bluesky is built on. There is an SDK for Python.

The core thing to know for this implementation is the client object, that lets you interact with the Bluesky programmatically. In order for your application/script to authenticate with the Bluesky server, you need to generate an application password. After authenticating and creating a client, you can use the send_post(...) method to create a post.

Bluesky posts have a “link card”, which requires a specific data structure called an Embed. Embeds include a title, description, url, and thumb. Here’s how this looks on Bluesky itself:

As nice as thumbnail images are, they are optional. So for simplicity, I omitted the thumb field in my implementation. This meant my link cards will end up looking blank, but an option is having some kind of logo for my personal brand and using that as a default, which I might implement later.

A key thing to note is that post content is limited in character length. For Bluesky, this is 300 characters, so we’ll want to be aware of this when scripting.

After creating the embed from my metadata, I use the send_post(...) method mentioned above. This method can return the URL and content ID for the post. Right now, I’m not doing anything with what’s returned, but I might want to write it to custom metadata for the post. So there’s two future features for this script!

Mastodon

Mastodon also has a Python library, and you can create a client (using an access token generated in the application). In a sense, it’s easier to work with the Mastodon library in that their servers handle the construction of the link cards/previews on the app. The library provides a similar client object. The client.status_post(...) lets you provide a status (body text, including the URL) and visibility (whether the post should be public, unlisted, or private).

Here’s an example of what a linked post looks like on Mastodon:

Again, it’s possible to post images/media to Mastodon, but my goal is quick syndication, so this isn’t something I want to handle with the script. Similar to Bluesky, the method returns a dictionary that includes the post ID and URL. Again, a stretch goal is to write this to the post metadata. Finally, Mastodon has a longer character limit of 500 characters — however, I don’t feel like I lose anything by forcing myself to stick to the 300 character limit from Bluesky. Also, the URL is part of the post in Mastodon (something to keep in mind if you’re developing on your own!).

Structure and setup

When I was programming in high school, I thought pseudocode was kind of silly. But it really helps to map out the overall logic and methods I’ll need to keep myself organized. And it speeds up developing with Gemini or ChatGPT if you already have a sense for the core logic. If I start with a plan for the script’s logic, going to an LLM lets me finish the project much more quickly.

So here’s a mockup, using some templates from other scripts I’ve used to work with markdown, YAML, or TOML. It translates the concepts from the steps I wrote earlier into blocks for methods, loops, and if statements:

# Import block - need to add atproto/mastodon, probably other libraries. 

# Configuration block - constants, retrieving keys, logging etc.

# Methods
	# Content handlers YAML, TOML.
	# Syndication functions, create sessions, etc.

def main()
	#0. Use argparse for input. 
		# Need directory to crawl
		# Optional testing mode.
        # Mode for testing clients?
	
	#1. Create clients (Bluesky, Mastodon)
	
	#2. Parse directories
		# Walk through directories, find each markdown file
			# If applicable
            #   Extract front matter, 
            #   Add to manifest.
            # else end

	#3. Execute steps
		# Loop through manifest
			# Extract URL and ping
			# Syndication/Test output
				# Update front matter to indicate as syndicated. 

if __name__ == "__main__":
    main()

I wanted the script to be agnostic on YAML or TOML (Hugo supports both for front matter), which means that the content handling logic needs to process both. That’ll complicate the method structure a little bit. Just like the leaf bundle vs. markdown filename point.

One realization I’ve had while writing this up is that it would be relatively easy to build something that doesn’t use links. I could add a posts directory to my site, and point this script at that directory to publish posts. These could be backed up on Github, left with draft: true and syndicated without being posted to my website.

It would also be a short hop to use this script with a tool like Obsidian, which makes use of markdown and front matter for note-taking. This lets you write and plan posts from your note-taking app, and Obsidian could become a home base for sharing and posting to multiple social media sites. Applications like this are why coding is fun and empowering!

On the topic of front matter it’s easy to map out new fields: I need a way to indicate which targets the script should syndicate to, what the content should be, and whether the post has been syndicated. While targets was my first choice, Hugo reserves the target keyword for link attributes (like target="_blank"). Using syndicate_to avoids any potential namespace collisions and makes the intent of the field explicit.

Here’s what my proposed front matter looks like in YAML:

---
title: "Syndication System Test"
date: 2024-01-01T12:00:00
draft: false
slug: "stealth-test-1"
syndicate_to: ["bluesky", "mastodon"]
microblog_content: "Testing my new syndication script. 🤖"
syndicated: false
---

Next up, we’ll set up the .env file. I’m going to include the BASE_URL for my site here, so I don’t need to load both the .env and Hugo config.toml. This might be a little sloppy, but I don’t anticipate changing domains any time soon:

# Site Configuration
#No trailing slash!
BASE_URL=https://www.yoururl.com

# Bluesky Credentials
# Use an App Password, not your main login password!
# Settings -> Privacy & Security -> App Passwords

BSKY_HANDLE=handle.bsky.social
BSKY_PASSWORD=xxxx-xxxx-xxxx-xxxx

# Mastodon credentials

MASTODON_API_BASE=https://mastodon.social
MASTODON_ACCESS_TOKEN=long-string-of-characters

Finally I told Git to ignore the .env, adding the following block to my site’s .gitignore:

# Environments
.env
.venv
env/
venv/
__pycache__/

Conclusion

This is a good stopping point for this post — I wanted to give a bit of the theory before publishing the final project. Coding can be kind of mysterious, and it’s helpful to show how you can get a good structure going for your ideas.

This script already works, and this is the first post I’ve syndicated using this approach. My next post will talk about some of the difficulties that emerged in building the script and a link to a github repo to so that you can use it with your own website. Hopefully this inspires you to work on something cool yourself!

Sarah Moir: AI and Tech Writing Strategy

Fri, 21 Nov 2025 15:37:16 -0500

Over at This is important, Sarah Moir has an excellent discussion of AI strategy for technical writers and documentation teams.

In particular, I really agree with her on this:

You can invest in building a chatbot with a tool like Fin, Inkeep, or Kapa. But I don’t recommend placing the chatbot on the documentation site.

When you build your own chatbot and provide it on your docs, you create uncertainty for your customers and readers:

Is the response going to contain accurate and trustworthy information?

Is this chatbot going to be more reliable than ChatGPT or Claude?

Documentation is perceived as an authoritative source of information. If the official documentation provides a way to get inaccurate or misleading information, readers might lose trust in the documentation itself, and ask: Are AI chatbots docs? (No.)

The role of docs as an authoritative source of information means that we shouldn’t to using AI as the main interface for docs. The risk of error undermines that function.

However, we should think of ways to meet the users with the interfaces they choose to use (browsers, in-app elements that direct to docs). Balancing this tension and having users understand the risk is really something we need to have in mind as technical writers.

It’s definitely something I’ve been thinking about lately. I’m currently finalizing a series of posts that act as a “snapshot of where we’re at” regarding generative AI and technical writing. I’ll be framing my posts around how generative AI might contribute to our practice, how it impacts how people access docs, and how we might need to change our practices for documenting generative AI solutions. It’s an interesting set of problems and opportunities and it’s great to have posts like Moir’s to help elevate the discussion.

Fabrizio Ferri Benedetti: Documentation Theatre as a Service

Sat, 15 Nov 2025 13:50:03 -0500

Google just announced Code Wiki. The timing of this is kind of personally frustrating, since I was deep into a post about where AI tooling and software documentation is at in the year 2025. Now that post is going to get a couple of extra paragraphs.

The copy is certainly striking, using phrases like, “Stop documenting”, “No more stale docs. Ever.” Understandably, this hits close to home for technical writers. After all, we’re in the business of producing docs.

What the tool does is kind of provide a seemingly “complete” set of documentation in a web interface, along with an instance of Gemini that you can chat with. The main mode is descriptive, explaining the architecture of the repository, which makes sense if you’re trying to understand the project as a codebase. Most of us aren’t working with libraries at that level. It’s impressive, but kind of weird. I really recommend pointing it at a repository you’re familiar with, and comparing the structure of the output to the official docs (a good example is Code Wiki’s approach to Flutter and Flutter’s docs).

Calling it a wiki is particularly strange — wikis center collaboration. The promise is that the service will own documentation. While this is probably a nod to these tools having a superficial appearance to GitHub’s wiki feature, it’s really different in spirit.

Fabrizio Ferri Benedetti has a spirited rejoinder that is really worth reading:

These tools [Code Wiki and DeepWiki] can fulfill the role of project summarization. They’re helpful when trying to explore poorly documented codebases and get a sense of how the pieces fit together, but they stop short of anything that could be called “docs” (and perhaps that’s why they shyly chose “wiki” instead). I would describe their output as byproducts of an LLM digestion process (yes, blergh).

It’s impressive for the first ten seconds, but as you start reading, you begin to notice that for most complex projects, the wiki is at best dry reference, at worst a dumpster fire of hallucinations, Escherian information architecture, and subtly wrong facts and diagrams. This is not a lazy dismissal: read the comments on Hacker News to get an idea of how dismal their results can be.

As is unfortunately common in this moment, the hardest part of our job is aligning with people who don’t understand the function or role of docs:

What makes me furious with the heat of a thousand Suns is the fact that some devs could be lured into thinking that this sort of ersatz manuals can check the docs box at all. That some could find these self-inflicted wikis a valid replacement of human-made docs shows the same kind of ignorance (or cynicism) about technical writing that folks display when praising art made by AI.

Docs are a product. They require sustained and intelligent effort over a long period of time, as well as a strong community ready to contribute. Docs are the mirror and lore of your code and design, instruments that help you think about what you are architecting and developing. Docs serve purposes and needs. Great docs explain, guide, help, and illustrate. They’re deeply flawed and human. They must be.

The whole post is great, but in particular, this conclusion:

Let’s draw the line: docs generated entirely by AI should never ship to users. You can use AI judiciously to audit your docs for gaps, to spot inconsistencies, to generate first drafts that you’ll edit later. But the moment you let any LLM have the final word on what users will read, you’ve abandoned the basic contract of docs: that someone who understands the system has taken responsibility for explaining it truthfully.

This last sentence is a powerful encapsulation of the value of docs, regarding user expectations, responsibility, and serving as an authoritative source of knowledge.

Tim Berners-Lee: Podcasts, AI, and the Future of the Web

Thu, 13 Nov 2025 15:37:16 -0500

I’ve been posting a lot about technical writing recently, but I also like thinking about the Internet. This is a really nice interview with Tim Berners Lee on Decoder (the Verge’s podcast).

First up, on podcasts…

They always try to persuade you to use the app, because then they have more control, they can track you better. But also with podcasts particularly, I use a podcast program, a generic podcast app, that I can listen to any podcast with.

For me, that’s the web as it should be. You could send me a link to a podcast, or I can search for it and I can keep track of all the hundreds of podcasts I’m interested in. It is a bit like keeping bookmarks on the first original browser. So, to a certain extent, podcasts work well. But if people end up on the app and then are tracked and not using the podcast app, then not so. All that tension is huge right now for the web, yes.

Which echoes a lot of what I love about podcasts and blogging.

But really, there’s very insightful discussion about where the web is at now, and where things are going in the age of LLMs:

At the beginning of the web, you made a lot of people with a lot of power agree to participate in some standards. You made them agree to participate in browser standards. There was a ferocious competition among browsers at that time.

It seems like we’re about to enter a period of ferocious competition in browsers again, which I want to come to. But at that time, at the beginning of the web, there was a lot of competition in browsers. Microsoft was brought to heel in an antitrust case, because there was such ferocious competition among browsers.

How did you go about convincing all of those companies and all of those people to adopt your standards and say, “We actually have to be good stewards of the collective”? Because that doesn’t seem like a thing that could happen today, but you were able to do it at the outset of the web. How’d you do it?

By persuading them that one web was going to be really good. If you have just one web, it would take off exponentially. If we had many little webs, they would each die. People realized that and they managed to persuade the governance within their platforms, their managers and their boards, to make this one web. They knew that if they fought over incompatible versions of HTML, then the web would not take off, like it would if they made one web. If they made one web, then one web would take off and become huge, and then their part of that web would be itself huge.

Could you make that argument today? And what technology would you make it about?

A lot of people would wonder whether you can make it with AI. There is no World Wide Web Consortium (W3C) for AI, which is bringing everybody together in one room. Some people have suggested there should be something like a CERN (The European Organization for Nuclear Research) for AI, some big high-energy physics lab in some big international lab that develops AI. That way you can really optimize both the development of AI, but also prevent the thing running away, so you can build containers around it, for example.

Also worth thinking about is how AI is changing how we consume and access the Internet. Major companies race to implement new browsers, whether governance and new standards will emerge, and companies like Cloudflare work to monetize AI access to your website’s content. It’s a good discussion, and I will definitely be looking into picking up the memoir.

As much as I’m leery about the prospects of Perplexity’s Comet browser, using an RSS reader is kind of like using a headless browser, and AI is becoming another form of interface for content on the web. The financial incentives shaping popular sources of content are definitely going to shape how we communicate both personally and professionally. If you produce web content (docs, marketing, etc.), it’s worth being aware of these structures and how they’re changing.

KCS and Technical Writing

Thu, 13 Nov 2025 00:00:00 +0000

In a recent post, I covered various knowledge resources and docs-sites, including a brief discussion about knowledge bases. A common practice for building a knowledge base is Knowledge Centred Service (KCS). If you’re a technical writer, you’ve likely encountered it—and maybe felt uneasy. KCS involves service team members creating articles that look a lot like your documentation. This can feel redundant, or worse, a threat to your value as a technical writer.

My goal for this post is to explain how KCS and traditional technical writing (i.e., writing comprehensive guides for a product or service) differ and, in fact, powerfully supplement one another.

Warning: This is a deep dive! If you’re a leader or Technical Writer trying to figure out how to have product docs work alongside Knowledge Centered Service (KCS), this post is for you. Here is the TL;DR:

The overlap is a myth: Traditional documentation and KCS articles are distinct magisteria (separate domains) that complement each other.

Docs are proactive: Technical Writers create the foundational “shared language” (guides, reference) that users and support staff need to even discuss a product issue.

KCS is reactive: The Solve Loop is a bottom-up process, driven by support teams fixing specific user failures. Docs should be linked and validated, just like KCS articles. Technical Writers shouldn’t be the authors for KCS articles or the bottleneck on publication.

Strategic Value: Technical writers are well positioned to contribute to KCS in the evolve loop as a strategic partner. They can help define the process and templates for KCS, and use the performance data from the Evolve Loop to proactively improve the official product documentation.

What is KCS?

KCS is a practice for service teams. A service team responds to issues from customers (internal or external). This practice has been developed by the Consortium for Service Innovation, a non-profit coalition dedicated to excellence in customer engagement.

What is KCS meant to solve? Organizations without explicit frameworks for capturing and communicating knowledge struggle to scale. Tacit knowledge, held by key members of the community is tied to that individual. While that individual is a valuable resource, they can become swamped — they are only one person after all! Worse, if that individual leaves an organization, the organization suffers as a whole, since their knowledge goes with them. The goal is to engineer ways of working that transform implicit knowledge into explicit artifacts or resources (capture).

Additionally, even if you successfully capture knowledge, it then runs the risk of becoming stale, or out of date. So knowledge management frameworks typically involve some kind of process for validating or maintaining your knowledge. Stale or out of date resources need to be validated, updated, or removed.

The promise is that KCS lets teams answer questions quickly with the latest collective knowledge, optimize self-service for known issues, and drive data-driven improvements for products and services.

KCs proposes that service focused organizations structure their workflows around two loops for building and evolving knowledge resources:

The Solve Loop
The Evolve loop

I’ll briefly explain both, and talk about how you might interact with them as a technical writer. Note: I’m not certified, but I’ve had exposure to the methodology, and I’ve been considering working towards certification. You can view detailed resources on CSI’s library detailing KCS v6.

The Solve Loop

Here’s the key insight: customer support teams function based on knowledge. A customer experiences an issue with a product, and the support team is equipped with the knowledge to identify the cause and work towards a resolution. When they achieve that resolution, hopefully they have that knowledge in case a similar issue arises. In resolving the problem, the support team is building and validating their understanding of a product. KCS proposes that support teams leverage that moment for two specific knowledge management tasks: capture and validation.

Capture occurs if the team don’t have any existing knowledge resources that solve the issue. In this case, the support team does what support does best: investigate the issue and move towards a resolution. As they’re doing this, they create an article that identifies relevant background features, the source of the problem, and the steps they take to resolve the problem. After verifying that the article is complete and records the solution, it is published to the knowledge base, ready to be reused the next time a similar issue arises. This knowledge base can be internal or externally facing.

To facilitate capture, KCS suggests a basic content model of an article, and to use simple templates with a consistent structure. This helps simplify writing and reading articles. Articles are typically stored in a database and retrieved through search. Because content is generated on a per-issue basis, building a navigable information architecture isn’t a priority in KCS implementations. The point isn’t to build a resource that is easily traversed by a human in a browser, but to capture and retrieve knowledge. This is a pretty serious perspective shift from how technical writers approach content design — often by thinking about user needs and coverage for a range of topics.

Here’s an example of a KCS resolution article from Salesforce’s Help Center:

As a brief aside, some work with LLM-powered chatbots suggest that this kind of clear structure is beneficial for reuse via LLM as well. Continuing to use Salesforce as an example, their Agentforce chatbot is the primary way for users to discover these help articles.

A key point in KCS is that reuse is review. Validation is the process of confirming the quality of existing resources. A well functioning KCS team searches existing articles to see if the problem has a known solution. If there is an article containing the solution, they validate that the article is complete and correct. During the validation step, they may make minor improvements, and they link the article to the customers tickets. If the article is incorrect, then the article is updated in line with the same steps as in the Capture path. The process is one of continual improvement, which limits the need for costly comprehensive audits.

Here’s a flow chart detailing the process, including steps for more complex solutions or articles that need improvement. If the knowledge base is leveraged for self-service (customers resolving their own issues), an additional step can be added to validate that the article meets standards before being made available to customers:

It’s important to note that there’s no sense in which KCS is complete. Knowledge is constantly evolving and created in response to new needs. The methodology is fundamentally bottom-up and focused on continuous improvement of a growing collection of articles.

The Evolve Loop

The solve loop occurs at the event level, where knowledge is produced and used. The evolve loop is a collection of organizational practices meant to ensure the overall health of your knowledge practices and organizational buy-in to KCS. While it sounds like big picture thinking, the evolve loop also involves practices at the article, contributor, and management involvement levels.

The evolve loop is broken down into four key practices:

Assessing content health
Process integration
Performance assessment
Leadership and communication.

Assessing content health involves using techniques that might be relatable to you as a technical writer. It involves reviewing content to ensure that it meets the structure, and assessing the state of individual articles. It also involves things like defining content standards and ensuring that people are aware of these standards. As the solve loop is bottom-up it says nothing about when to retire articles, so as part of the evolve loop, you will want to set up processes for archiving old articles and cleaning up legacy data (if you’ve ever maintained an internal wiki, you’ll know how important this task is!).

Process integration is about aligning tools and behaviour to ensure that the solve loop is low friction. It involves ensuring that the ticketing tool or CRM and the knowledge management tools are closely aligned. Lowering friction is vital to the success of a KCS program: you need to focus on how issues are individuated and knowledge is retrieved and created in the flow of work. Ways for managers to ensure adherence to KCS methodology are also vital — while contribution will be varied across a team, it’s important to coach support team members as a whole and build skills. This includes building habits while working to retrieve information from your docs site and knowledge base.

I feel like this point is a more significant stumbling block for orgs than they tend to think! If teams are building both a docs site and a knowledge base, then cross-publishing, content duplication, and search are significant risks of failure when implementing KCS.

Performance assessment focuses on measuring contributions and the success of the program. It involves carefully defining goals, ensuring that there aren’t game-able incentives for contributors, and facilitating leadership. It also involves defining roles and ensuring that people who have demonstrated competency and awareness of the knowledge framework and standards are enabled to contribute or provide validation. Competency is key, some service representatives might need to demonstrate core knowledge framework competencies before they can fully contribute or validate content.

Leadership and communication is about making the process understood by the organization as a whole. People need to understand how the initiative relates to strategic goals and ways in which they can contribute or relate to the business as a whole. It involves developing and articulating a vision for the KCS process as a whole and ways of promoting and encouraging participation. The KCS practices surrounding leadership heavily discusses metrics, but I do think they take a holistic view noting that it carries throughout the org. Strong KCS leadership involves building collaboration with over teams.

Both loops are continuous processes, driving the knowledge culture at an organization. The solve loop generates content, and the evolve loop reinforces and improves the content and practices as a whole.

How does it relate to technical writing?

Lets come back to that original complaint:

So all of my support staff are now going to be writing on top of all of their ordinary duties, while over on the product or engineering team, we have a perfectly good technical writer. This all seems to be going very wrong! My support team is writing rather than solving problems and the technical writer output isn’t solving customer problems.

Or alternately, from a more strategic perspective, it might look like the technical writer is producing significantly less content than the KCS team. Building and maintaining two platforms that look very similar makes the team that is less directly tied to revenue look more expensive or less productive. And the unfortunate truth is that support has a much easier time tying their initiatives to churn, CSAT, and deflection rates, since this is data about customers.

There’s a couple of points to say about this kind of confusion, which I want to end my post on:

Technical writers have skills to contribute to the KCS ecosystem, but need to be brought in carefully. They are ill-suited to author articles. And there are opportunity costs and multiple models for contribution.
Docs and knowledge base articles (as construed by KCS) are distinct, but supplemental worlds. Docs are proactive and foundational, while KCS is reactive and contextual. And these are both resources people need!

Technical writers can contribute to KCS

Doing KCS is a lift — it’s difficult and ongoing, requires organizational buy-in, a lot of training, and external factors need to align. In many ways, the processes, practices, and standards it suggests are aspirational for a company, the north star that guides support operations.

The mistake is to think that the technical writer should be authoring at the level of the KCS article. Technical writers aren’t engaged in the same interactions that drive the solve loop. They do, however, have expertise in the kind of writing that KCS aspires to, and in fact, a technical writer can be a valuable asset as part of the assessment and editing flow in the solve loop.

There is, however, a concern with this model: this can diminish both technical writer velocity and KCS velocity by introducing a bottleneck on publication. There are often more support agents than technical writers and technical writers are already busy keeping pace with your engineering team’s output.

My suggestion for this kind of workflow is to view the technical writer as a coach, rather than as a check or valve — they should champion writing standards to the contributing team and they are experts in automated tools should be used to help ensure the quality of content in KCS articles.

The other potential route for involvement is enlisting their help in content modeling and KCS design. They can help define the structure of your article types, and provide guidance on how to add categories and other kinds of metadata to your knowledge base, ensuring that these things align with your broader product guides and resources. Technical writers are uniquely positioned as a high-value add when it comes to defining and explaining the product and bringing them into the evolve loop can improve the ecosystem as a whole.

Still, I think leaders looking to involve technical writers in their KCS flows should be cautious. KCS is demand driven, and technical writers highest-value time should not be spent as a reactive editor. The tactical route for involvement is enlisting their help in content modeling and coaching. A stronger use is as a strategic partner, helping shape the architecture of your knowledge articles, and benefitting from the evidence that a KCS system can provide.

Different content for different purposes

The complaint I started with stems from a simple confusion: we tend to refer to any written output of business units as documentation. But product/engineering embedded technical writers are doing something fundamentally different from KCS. To borrow a term from philosophy of science, product documentation and KCS articles are distinct magisteria.

Stephen J Gould’s idea of non-overlapping magisteria (NOMA) is that religion and science are directed at different questions, with different standards for evaluating correctness. Science is directed at answering questions about how the world works, while religion is directed at answering questions about morality, meaning, and how we should live. The methods of science aren’t suited to answering those questions, and the methods of religion aren’t suited for answering questions about how the physical world works. While NOMA itself is a philosophical concept often debated, the core idea—that different domains (magisteria) have fundamentally different questions and methodologies—is a powerful lens to apply to technical writing and KCS.

Product documentation (the proactive and foundational magisterium) is forward-looking — articles define the intended operation of the product, tell users what the product does, how to use a feature correctly, and provide reference for technical details. They create a shared language. KCS articles (the reactive magisterium) are bottom-up, and created after a failure. They tell the user why something broke, and how to fix that specific contextual scenario. One defines the map, the other fixes the potholes.

As anyone who has built something knows, users tend to surprise you. Things will break in ways that you can’t anticipate — or rely on configurations outside of what product managers, QA teams, and technical writers can anticipate. The knowledge built by support teams is a valuable guide to what happens after the unexpected happens.

More importantly, KCS is a reactive posture. A central challenge for KCS is adapting to changes or new products. It’s approach allows a team to rapidly scale a knowledge base, but it relies on customers and support sharing a common ground for communication.

Technical writers should be positioned to be proactive. Technical writers create the material for building a shared language between internal staff and users. There needs to be some kind of common ground between the customer and the support team to identify and resolve issues. Users acquire that language from the product, the documentation, and their onboarding.

KCS extends that base of knowledge to more complicated scenarios where the system encounters potential failures. Support staff, working from KCS, will go from their knowledge articles to the docs when there are gaps in their knowledge, extending and transforming that foundation into new knowledge. If they’ve internalized use-as-review, then they’ll be encouraged to create tickets and supplement the docs with their own feedback, just like they identify bugs in the core product.

This division of labor is precisely why the two supplement each other. KCS articles, with their high volume and explicit ties to support tickets, generate powerful data. If a thousand tickets are being solved by a specific KCS article on a core feature, it tells the technical writer one of three things:

The official documentation for that feature is missing context
The official documentation is not findable
The product has a defect that needs a dedicated guide

The data transforms the technical writer’s work from guessing what users need to evidence-based documentation planning. The solve and evolve loops are sources of data for informing your practice. The core idea is that technical writers are strategic partners who can benefit from data, but help guide the standards and improve the KCS knowledge base in the evolve loop. The more senior a technical writer is, the better positioned they are to help with conversations regarding metadata, retrieval, and content planning to ensure that knowledge base is healthy and up-to-date.

Three contribution models

Hopefully this has convinced you that technical writing and KCS aren’t in conflict, and when done right, are complementary approaches to providing self-service resources. I think technical writers and be involved in KCS in several ways that benefit the program.

Here is a table summarizing each of the three approaches:

Feature	Technical Writer as Editor (Tactical)	Technical Writer as Coach (Enabler)	Technical writer as architect (Strategic Partner)
Primary Focus	Daily quality control and editing of articles	Training support staff on standards and tools	Defining structure, taxonomy, and feedback loops
Role in Solve Loop	Gatekeeper/bottleneck: Reviewing and editing articles before publication	Trainer: Championing writing standards, templates	No direct involvement
Role in Evolve Loop	Perspective on content health, performance assessment	Facilitator/communicator - helps managers relate	Uses KCS data to identify improvements in product documentation, insights from product docs inform KCS practices
Core Value Proposition	Improved KCS article quality	Faster adoption of content standards by support staff	Evidence-Based Strategy
Risk/Drawback	Velocity bottleneck, technical writer is pushed into a reactive posture, potentially over-leveraged.	Limited strategic impact, doesn’t utilize insights from KCS	Requires tools for data analysis, expertise
Relationship between Docs and KCS	Shared content, responsibility	Technical writers are expert communicators, facilitating comms skills	Distinct magisteria: KCS informs docs strategy, docs are the foundation for shared understanding of product

While I tend to prefer the third model, I think there are value-adds that technical writers can provide in each. It only becomes a concern if we think that KCS can supplant the proactive, forward looking role that good docs provide.

Concluding thoughts

Like I mentioned, I was exposed to KCS through my work. Technical writers and support teams should be closely aligned, and I’ve benefited from KCS content directly. I think it’s a powerful framework, and it gets to the core of something about service-based work that should inform how teams think about building, maintaining, and transferring knowledge.

It’s easy to view it as something in conflict with or replacing docs entirely. But I hope I’ve demonstrated some of the ways that technical writers can contribute to a KCS ecosystem through it’s processes, the ways they can benefit from KCS, and the fundamental value that technical writers have for a product.

The reality is that we have tight budgets, varying incentives, and lots of demanding customers. Transformation and practice is hard, but worthwhile. Adopting KCS isn’t about giving up proactively written guides and reference material, it’s about building a culture that values knowledge sharing and use. In this light, companies need to address questions about governance and architecture. The questions are part of KCS, but technical writers are well suited to contribute to answering these questions.

It can be a difficult road building that kind of culture at a company. I think that technical writers as content strategists can be helpful champions, co-architects, and beneficiaries from KCS. I think there’s a deeper question of content architecture that I’ve hinted at. Tooling (like docs-as-code or a CCMS) gives technical writers a powerful authoring environment, but using those effectively is a core competency of technical writers, not support staff. Enterprise knowledge management solutions give support teams CMS/databases that are easily linked to customer tickets, but the bifurcated systems here create problems (analytics, search, etc.).

A unified content pool is the dream, but how do you balance the competing needs? Building and designing these systems is tricky to begin with, and made even more urgent as retrieval augmented generation (RAG) and LLMs depend entirely on structured, authoritative content pools for accurate retrieval. KCS struggles with changes due to its reactive posture, and I think technical writers can help with propagation. Involving technical writers in the evolve loop is part of the answer. But these are thoughts for future posts.

Here’s the takeaway for leaders and technical writers: KCS is not a replacement for documentation; it’s an opportunity for evidence-based strategy. Strategically minded technical writers are well suited to move beyond serving as an editor to leverage KCS data. Helping to build a knowledge ecosystem that serves both the product and the customer better than either system could alone.

Note: Thanks for making it through this deep dive! If you found this strategic breakdown valuable and want to support more content like this, consider buying me a coffee. I’m currently between positions, and I appreciate the support.

Tech Writing Webring

Sat, 08 Nov 2025 00:00:00 +0000

Following a discussion on LinkedIn about why more technical writers should blog, I’ve joined a new project: the tech writing webring, started by Casey Smith.

What’s a webring?

A circular structure of websites that are linked together, organized around a theme or perspective. Basically this was a way to help people discover content prior to search engines. It’s a fun, retro-internet approach lines up nicely with my goals and ideals for this site.

How do I join?

To join this webring, add the links to your site and submit a pull request adding your site to sites.json. See the README for instructions.

Implementation details

Implementation is driven by a simple agreement: all members display a block of links to help people discover other sites in the ring. Sometimes this is done with javascript, but what’s cool about this ring is that the requirements for adding it to your site are really pleasantly minimal.

Note, going by LinkedIn discussions, this part is optional - but it’s part of the fun!

All you need to do is add a block of links somewhere on your site, replacing YOUR-SITE-URL with the URL of your site:

Part of the <a href="https://caseyrfsmith.github.io/webring/">tech writing blog webring</a> | 
<a href="https://caseyrfsmith.github.io/webring/navigate.html?action=prev&site=YOUR-SITE-URL">Previous</a> | 
<a href="https://caseyrfsmith.github.io/webring/navigate.html?action=next&site=YOUR-SITE-URL">Next</a> | 
<a href="https://caseyrfsmith.github.io/webring/navigate.html?action=random&site=YOUR-SITE-URL">Random</a>

These are connected to the ring, and you can use those to find people who also blog about technical writing. The final step is submitting a pull request to update the list of sites in the public GitHub repository’s JSON file.

Adding this to my site involved four steps:

Defining a partial (reusable block at the template level) to add the webring text to content on this site.
Adding the partial to a conditional block in my singles layout(the template) that handles specific elements for blog pages (publishing the title, date, etc.).
Updating the site with these new elements.
Making a pull request to add my site to the webring.

What’s next with this blog

I’ve been taking a little time off from blogging recently, focused on recharging my batteries, but I have some long-form content coming down the pipeline.

Upcoming posts

I do have a couple of long form posts that are coming down the pipeline. There’s been some good discussions in Write the Docs about knowledge-centered service (KCS) and Salesforce, and it’ll be nice to get a bunch of thoughts about knowledge management out of my brain. I hope they’ll help fellow technical writers if they encounter these very different methodologies in the wild.

These pieces are in the editing phase and are definitely long form content (3,500 words-ish). My goal, however, is to shift back to shorter, more frequent content once these are published. So keep that in mind if you’re going to follow my RSS feed.

How I want this site to work

The other side is I really want to finish the publish-on-own-site and syndicate everywhere (POSSE) script for this Hugo site, and share it on my Github page. The goal is to have a Python script handle syndication for blogposts to Mastodon/Bluesky, using the front matter from the posts (typically a short description).

This way, there’s always RSS for places where you can control how you receive content from me, but then social media becomes a way of getting additional discovery out there. That way everything I author is stored here.

The big thought is to follow cool projects like this one by Jon Brown which use federated social media as the comment system for your site. This would transition the discussion from one-to-many (me broadcasting) to many-to-many (easier, direct discussion).

These project developments will probably also end up here, so if that sounds interesting, feel free to follow along in an RSS reader (for now!).

Thinking Strategically About Documentation

Tue, 21 Oct 2025 00:00:00 +0000

As a technical writer, you will contribute to different kinds of documentation projects. It’s important that documentation responsibilities are aligned with a coherent strategy.

One of the biggest things to know about documentation (that people don’t think about) is that the word documentation is polysemous. The various meanings pretty much guarantee that at more chaotic employers you will be pulled in different directions unless you have a clear strategy or posture when it comes to working as a technical writer.

I didn’t go into the various definitions in my previous post, but there are three main meanings at play in a company:

Official information source — The canonical guide to a product or service.
Normative guide — This formalizes a decision and guides the behaviour of people (think project documentation, process documentation).
Evidential material — Evidence that a control, process, or system is in place.

These three senses of documentation often overlap: team process documentation is from an authoritative source (a manager) and can be a form of evidence that the team does something (for a compliance audit), but it also guides behaviour (the process is only valid if people are held accountable/follow it). Sometimes these definitions come apart: a user manual describes how to use or complete tasks. It’s not a guide to how people should go about working (in the same sense as process documentation) or a guide to what should be done as part of a project. And the same piece of documentation can function differently depending on how an engineering team operates. An OpenAPI spec, depending on spec-first or code-first engineering, can be either guide the writing of code or describe what has already been written.

Technical writers can contribute to all three kinds of documentation! The problem arises when employers fail to carefully define lanes of responsibility and prioritize work for technical writers. And, unfortunately, this is particularly common for teams where they feel the need for a technical writer, but don’t have experience with one on staff. In this case, the company is at the bottom of the docs hierarchy of needs. Any documentation is good documentation, and the incoming technical writers are supposed to deliver the solution to their problems. Managers and leaders from across the company will see you as a resource they can use to help with their documentation needs, in whatever ways they’ve internalized the meaning of the word documentation.

This is a recipe for chaos and the technical writer becoming overwhelmed. And it’s why it’s important (as a technical writer) that you build this shared understanding with your immediate manager and ensure it’s communicated to your company as a whole.

Having a clear sense of why, what, who, where, and how is part of what I call a documentation posture or strategy. Aligning your work with a strategy involves framing how readers will interact with your output and where your core responsibilities fall.. These can then inform your metrics for evaluating your output and ultimately, which platforms you’ll work with. Having an explicit, shared understanding between you and your manager is key for your success as a technical writer.

This post is a bit of a brain dump of terminology used in software companies. By the end, however, you’ll have an understanding of what goes into framing a coherent docs strategy and ways in which you can define your responsibilities as a writer. Hopefully this is helpful to leaders considering working with technical writers, or technical writers trying to make sense of vague job postings!

Products, audiences, and support models

Since software products and support models can take various forms, documentation sites look very different from company to company. A lot of technical writing materials assume that there’s a single thing, “docs”, that we produce. But I think that there’s differences in the kind of output that are worth describing when framing your documentation posture. So, this post will be a brief guide to the different kinds of docs sites that you might have to contribute to as a technical writer working at a software as a service (SaaS) company.

For this post, I want to focus on a particular kind of thing that technical writers are uniquely positioned to contribute to: documentation sites. A documentation site is an electronic resource that provides material that meets documentation needs, and can be publicly available or locked down to require user logins. They are a living resource that is updated as your software product changes (unlike hardware manuals!). Documentation is a (typically written) electronic resource that lives on the docs site. It could be served as web pages, PDFs, videos, etc. and it can be authored through a variety of tools.

Unsurprisingly, there is no single or standard way of doing this. Understanding the audience’s needs is key to choosing the right solution. Here are a few different models for user needs that documentation sites can address:

Developers need materials that enable them to build with a software development kit (SDK) or application programming interface (API).
Administrators need guides oriented around common configuration and maintenance tasks for complex, multi-user apps.
Users need guides on how to complete certain tasks within an application (typically through a graphical user interface).
Users/admins/developers should have the option to self-support and troubleshoot common issues that arise when trying to use your product.
Internal staff need resources to provide support to customers experiencing problems with your software.
Internal staff must be able to easily create and find resources on their projects or how to work with other teams.
Internal staff need to demonstrate that they know what to do in certain circumstances and evidence to external auditors that processes exist.

In choosing a strategy, you need to have a clear sense of why users are coming to find documentation, how they’re navigating through it, and how you’ll evaluate whether what you are doing is useful. This will vary based on what your product is, who your product is for, what they’re trying to do with it, and how much involvement your customer facing teams have in the support process.

In the next section, I’ll break these down into central categories, and explain some of the tools that are used in building and maintaining them, and why you might adopt any mixture of these platforms.

Three models of documentation practice

So! I think bearing in mind the multiple meanings of documentation and the different product categories, there are three main approaches to meeting those needs: there are comprehensive guides, enhancements for user experience, and resources for normative guidance/evidence. As a technical writer, I’ve interviewed for roles involving, or worked on, each of these in some capacity. Each of these needs is better supported by different solutions, so I’ll explore each a bit more closely.

Comprehensive guides

The first category emphasizes documentation as comprehensive guides or resources. In these instances, the goal is to provide a resource that is like the full operational manual to your software. These are most often in place for products where they are intended to be consumed by technical, engaged users who are comfortable getting into the details of how your product functions. Often these products are for developers — who interact with your product through code — but there are cases where a similar level of attention is necessary for products with user interfaces as well.

It’s important for scenarios where your readers need to build understanding, but also refer to how the parts work to achieve their goals. When contributing to these sites, you’re trying to provide feature coverage. If it’s for administrators, you’ll provide guidance on how to configure integrations, user categories, and permissions. If it’s for end users, you’ll cover the main features and workflows in your app. Once you’ve achieved coverage and are able to maintain it, you can move on to focus on improving the experience and offering tailored learning paths or fancy interactive features.

In this case, you’ll often see webpages that use terms like “developer portal”, “API Guide”, or “Docs site”. You can find these at developer.product-name.com or docs.product-name.com (with the notable exception of Google Docs). These sites are often focussed on displaying content in an easy to read manner, and built to quickly get skilled people into interacting with your product through tutorials and code samples. Larger tables of reference pages are built from automated resources, like an OpenAPI spec — a standard way of describing an API and how it will respond to requests.

A Note on Content Architecture: CCMSs and DITA

While many of the tools listed below (Static Site Generators, or SSGs) focus on generating a single, static web experience (a single endpoint), large, complex organizations with numerous products, versions, or regulatory requirements often adopt a Component Content Management System (CCMS), frequently built around the DITA (Darwin Information Typing Architecture) standard. This is not a site type, but rather a content architecture where content is broken into reusable topics. This approach allows a single source of truth to be published to many endpoints (websites, PDFs, embedded help in apps) — which is essential for large enterprise products. This post largely focuses on web endpoints, so I’m including this here for the sake of completeness!

Here’s a quick breakdown of how these three categories come apart:

Site Type	Primary Audience	Core User Intent (Consumption Model)	Primary Business Goal	Typical Tooling/Stack	Example
Developer Portal	External Developers, Partners	Conceptual & Tutorial (How to build/integrate)	Increase adoption/API usage; grow ecosystem. Often multiple APIs and/or SDKs. Developers can manage/monitor services within the portal.	SSG (Docusaurus, Hugo, Sphinx), dedicated frameworks.	Discord developer portal
API Reference	External Developers	Reference (Lookup specific parameters/syntax)	Enable quick, correct implementation of code.	API Spec Integration (OpenAPI/Swagger + Redoc/Stoplight). Can be embedded in SSGs or platforms like Mintlify, Fern.	GitHub REST API Docs
Docs Site	External Users, Admins, Customers	Procedural & Conceptual (How to use/configure the product)	Drive successful product setup; reduce churn via clarity.	SSG (Hugo, Sphinx), CMS (traditional or headless), CCMS (Paligo, Oxygen) to a publishing endpoint.	MongoDB Docs

If you’re hiring a technical writer to contribute to these kinds of docs, you’ll want them working closely with your engineering team. They’ll need access to the API and test environments so they can verify that code samples function. Users might rely on the information architecture to explore, but often use a combination of search tactics to find the information that they need and quickly leave the site.

The bulk of technical writer resources on the internet are geared towards technical writers functioning in this kind of space. Why? Well, documentation is necessary for these products to be used. If you’re interacting with an API, there isn’t a graphical interface to guide you to completing key tasks. For apps that focus on user experience, however, things differ.

Enhancements for UX

The second approach is to build resources to supplement a user’s experience of a product. Generally speaking, companies that adopt this approach tend to have intuitive products or onboarding for user bases that are less likely to spend time working with specific references. These sites are less focused on in-depth product reference and more on providing resources that develop and enhance a user’s journey with a product. They may be built to support and develop skills through structured learning. Like other docs, these could be delivered publicly or as part of a customer portal.

These resources are part of the overall world of customer experience (CX). If you are contributing to this part of a docs strategy, you will be best served working within the CX function. Overall, the metrics here are deflection and efficiency. Is there a reduction in support tickets after publishing an article about a common issue? Are onboarding goals being met? Are certifications being maintained?

Rather than expecting users to navigate through these resources, there’s an emphasis on searchability and task-oriented content. There may be a higher volume of shorter, highly specific articles developed along with support teams. In some cases, there may be no visible navigation structure for external audiences (knowledge bases built explicitly to be searched, rather than browsed).

These kinds of resources live at domains like help.product-name.com or learn.product-name.com. They often make sense in contexts when there’s a larger or broader user-base that is less engaged with the technical details of the product, though some platforms make sense when it’s important to track or reward the development of knowledge.

Site Type	Primary Audience	Core User Intent (Consumption Model)	Primary Business Goal	Typical Tooling/Stack	Example
Docs Site	External Users, Admins, Customers	Procedural & Conceptual (How to use/configure the product)	Drive successful product setup; reduce churn via clarity.	SSG (Hugo, Sphinx), CMS (traditional or headless), CCMS (Paligo, Oxygen) to a publishing endpoint.	MongoDB Docs
Help Center	External users, admins, customers	Procedural & Task (Quick solve, self-service)	Deflect Support Cases; improve customer satisfaction (CSAT).	Customer Service Platform (Zendesk Guide, Intercom).	DialPad Help Center (contrast with their Developer Docs)
Knowledge Base (KB)	Internal support agents, sometimes external	Task & Procedural (Solve known issues efficiently)	Increase Agent Efficiency; ensure consistency of support answers.	Customer Service Platform (Salesforce Service Cloud, Zendesk).	Salesforce Help Articles – see this specific example for an example with no visible IA, but externally published and searchable. These kind of KBs are well suited to providing chunkable content for RAG powered AI tools.
Learning Management System (LMS) / Customer Academy	External learners (Users, New Admins)	Conceptual & Tutorial (Structured learning, Certification)	Structured Onboarding; reduce support load through education.	Dedicated LMS Platform (Teachable, Moodle).	Salesforce’s Trailhead

When contributing to these systems, technical writers usually partner with Support and Customer Success to identify high-volume pain points. It’s often the case that technical writers aren’t the sole contributor, or these systems are owned by people outside of the function entirely. Learning systems in particular are highly multi-modal, and dedicated instructional design professionals will work on LMSes. If a support team practices knowledge-centered service, support team members might author articles that you edit prior to external publication. There’s a variety of models here.

A quick note: training is an activity or event, but it is also sometimes used as a content type. Slipping between the two can happen here, just like with documentation! An article can be a self-training resource, an LMS is a guided experience that supports learning and training.

Guidance and evidence

Finally, there is the documentation that keeps the company running smoothly, ensures internal alignment, and protects the organization legally. These are rarely public facing, but as a technical writer, you’re often regarded as the expert on information architecture, governance, and clarity.

Common goals for these kinds of artifacts are alignment and compliance. Internal resources help teams align by making sure that engineers use the same UI components, new hires get up to speed quickly, and that decisions are logged and searchable. For compliance, the goal is often purely evidential — demonstrating that certain controls and processes exist and are followed.

Writers engaged in this kind of work are often embedded in ops or services teams, and work assignments come in to support experts or managers within a larger company. A technical writer has a domain knowledge in how to communicate processes clearly in writing that managers might not have, and help with standards and clarity on these kinds of documents.

Site Type	Primary Audience	Core User Intent (Consumption Model)	Primary Business Goal	Typical Tooling/Stack	Example
Team Wiki / Internal Knowledge	Internal Teams (Eng, PM, Marketing)	Reference & Process (Decide, Align, Onboard)	Organizational Alignment; formalize decisions (ADRs); speed up new hire ramp-up.	Collaboration Software (Confluence, Notion, SharePoint).	Gitlab’s Technical Writing Team Handbook
Component Library / Design System	Developers, Designers	Reference & Conceptual (Standardize UI, find reusable code)	Consistency & Scalability; enforce brand and UX standards.	Storybook documentation, Figma design system	Lightning SLDS
Compliance Docs / Audit Artifacts	Internal Governance Risk and Compliance (GRC), External Auditors	Evidential & Reference (Prove controls, show history)	Mitigate Legal/Financial Risk; achieve certifications (SOC 2, ISO, HIPAA).	Document Control Systems, SharePoint/Word, tools that generate reliable PDF/LaTeX output (e.g., Doxygen, MadCap Flare).	AWS Compliance Resources

Writers might not write every internal policy, but they can help create efficient templates, manage the structure of the wiki or repositories, and help enforce quality standards to ensure that critical knowledge is accessible and trusted. This kind of internal documentation has the potential to be the biggest spot where responsibilities can slip — if you are a technical writer embedded in an engineering team, you might produce internal documentation on Confluence regularly. This kind of expertise will look tempting to directors outside of your team.

Developing a posture

One of the core challenges of being a technical writer in changing or smaller companies isn’t just writing, but navigating the views of directors and managers from across a company. I previously talked about building a shared expectation with your immediate manager. Without a clear documentation posture on all three needs, it’s very easy to be pulled in every direction: struggling to maintain product guides, supplementing user support, and managing internal organizational knowledge.

This is why developing a clear documentation posture is critical for both your success and the coherence of your company’s knowledge ecosystem.

You should think of it as an explicit, shared agreement on four points:

Core responsibilities: For both technical writers and other internal staff. Which is your primary focus as a technical writer? Who contributes to other forms of documentation?
Success metrics: Adoption? Deflection rates? Internal efficiency and compliance?
Governance: Who owns the content? Who is responsible for the information architecture?
Platforms: Where will the content go? What tools and permissions need to be in place to work at scale for that platform?

By answering these questions and having a clear sense of platforms and responsibilities, you can move from having “docs” as a vague “need” or “requirement” and have a coherent plan for working with your technical writers as strategic hires within an organization. You can assess whether your docs are meeting needs, and come up with plans for improvement. This kind of clarity serves as a strong defense against competing priorities, reduces burnout, and sets up your staff members for success.

CT Smith: Docs-like-Stripe is a Cargo Cult

Mon, 20 Oct 2025 00:00:00 +0000

Great post from CT Smith at docsgoblin.com:

At a previous role, WE WANT DOCS LIKE STRIPE was directed at me, with full eye contact during a meeting, by a leadership team that refused to give me any money for tooling or development resources. I cracked and said “Stripe has like seven engineers on their doc tooling alone, I’m not sure what you expect from me with my current resourcing. Could you help me prioritize?”

I left shortly after this conversation. Trust, it’s been one of many times I’ve heard this in job interviews, chats with founders, really any conversation about documentation where the tech writers were outnumbered. Tech writers love lambasting this request when we get together to talk shop, pointing out that companies always want docs like Stripe’s, but but they don’t ever want to invest in docs like Stripe does.

It’s important to leverage expectations with the resources available, and the unfortunate truth is that companies tend not to have as many resources going towards their documentation. This is true not just for resources like investment or team members, but also in providing time and tools for people to onboard to your systems. I pretty clearly list the tools I’m comfortable with on my resume. I can adapt and learn new tools, but you’ll have to give me time to get up to speed with them — and this can be both the things that are documented by your vendor, but also the things you’ve built inside of it. And my first pass is not going to be at a professional level.

It’s also important to note what goes unsaid when someone relies on comparison and focuses on the presentation layer:

People who say this think that the docs are in the “look” or the tool used to build them, or even their perceived comprehensiveness or complexity. They think things like this:

If we have the same tool Stripe uses for their docs, our docs will be that good too!

If we make the docs look like Stripe’s, our docs will be good too!

If we have a lot of docs like Stripe, our docs will be good too!

They see the finished product, without any understanding of the kind of work and care that it took to bring it into existence, and say “Yes, just like that!” and then try to reverse engineer it based on appearances without ever going beyond the presentation layer.

Definitely a good reminder that indirect reference through an example is a bit of a shortcut in communication, and we should always strive to communicate more clearly.

Why Link Blog

Mon, 20 Oct 2025 00:00:00 +0000

A couple of my more recent posts have been “link blogs”, but what am I doing when I do that and why put the effort in at all?

What is a link blog?

A link blog post is a short blog post for something that I’ve read, which interests me. I’ll publish a link, some commentary, and any excerpts that interest me. The goal is for them to be brief.

This idea is loosely taken from Simon Willison’s Weblog:

I proposed two categories of content that are low stakes and high value: things I learned and descriptions of my projects.

I realize now that link blogging deserves to be included a third category of low stakes, high value writing. We could think of that category as things I’ve found.

That’s the purpose of my link blog: it’s an ongoing log of things I’ve found—effectively a combination of public bookmarks and my own thoughts and commentary on why those things are interesting.

I really enjoy reading Simon Willison’s link blog posts—they’re short and insightful. They broaden my perspective on working in and with technology. So I figured I’d share a little bit about why I’m adopting that practice on my own blog.

Why link blog?

The plan for this blog was to have it be a mixture of personal and professional content. As a technical writer, I’m a technologist. A user and creator of technology. So mostly, my blog posts will be about technology as it intersects with my life, my personal projects, etc.

There are three main reasons:

Simplicity
Building a record
Contributing to a better Internet

Simplicity

This is about simplifying my blogging practice some.

Like many writers, I find it easy to over write. If I get into a good flow state, all of a sudden there’s thousands of words in front of me, and not all of them are good. I have a folder in the GitHub repo for this site containing various drafts and ideas that I’ve been working on. Some may end up published, a lot won’t. Feeling comfortable putting a 3000 word post out there without an editor is something that takes time and effort. Anything that I put on the web is a reflection of who I am, to some extent, and this website is part of my professional presence.

While I want to write long form pieces, the significance and effort can be limiting, and it’s easy to fall out of a practice.

By identifying an alternate form of blogging, I can blog more regularly, and keep engaged with this website as a project. I have a rough limit of a couple of paragraphs of my thoughts about what I’ve been reading. The goal is to identify something of interest, then add something like a thought, a connection to something that I read, record my thoughts and move on. The simplicity of the format frees me from a lot of anxiety about having to polish something a bit longer.

Building a record

Like many writers, I really enjoy the act of reading. Books yes, but I still like reading articles, blog posts, interesting read-mes or conceptual pieces, wiki articles, and more. The variety and amount of written content is part of what makes the Internet a good and valuable thing.

Having a record of what I’ve read, and what thoughts those things have prompted in me is valuable for my own curiosity and learning. Sure I can bookmark things in my browser, but if you’re like me, your bookmarks are a messy morass. My RSS reader, Inoreader, is great and I routinely save things to come back to later, but also allows for stronger navigation of resources.

But with a link blog, I can add my own thoughts and connections. The blog becomes a record of what I was thinking about as I read those things. And that’s valuable for me when I come back to them later. If you’re reading and following this, you might be interested in the same kinds of things that I’m interested in and I hope that once or twice a week, some of my thoughts about the Internet, culture, or technology will be valuable for you as well.

Building a better Internet

The Internet is at it is best when its filled with multiple voices and perspectives. Amplifying other voices, platforms, tools, perspectives is an easy way to contribute to this version of the Internet. In many ways, the Internet of 2025 feels oppressive. But as Molly White notes in her talk at XOXO in 2024:

That’s because what really sucks about the web these days, what has us feeling despair and anger, has everything to do with the industry that has formed around the web, but not the web itself. The web is still just a substrate on which anything can be built. Most importantly, the web is the people who use it, not the companies that have established themselves around it.

And the widespread disillusionment that we’re seeing may actually be a good thing. More people than ever have realized that the utopian dreams of a web that could only bring about positive and wonderful things might have been misguided. That tech companies maybe don’t always have our best interests in mind. And that slogans like “don’t be evil” might be more about marketing than about truth.

With this knowledge comes power. The power to shape the web that we want to see, while fighting against the one that we don’t. The tech industry has structural and financial power of its own, to be sure, but the only thing that enables the kind of rot—and to quote Cory Doctorow, “enshitification”—that we’ve seen spread throughout the platforms that now form a large part of people’s online experiences, is the platforms’ stranglehold on the web. And that is tenuous.

I want a wild Internet, where people can easily create what they want, with minimal constraints from platform providers.

A personal blog is part of that project. It’s a way to contribute to more perspectives and share other voices that are writing and contributing to the same project. I hope that authors who find their way here get something out of my thoughts about their writing, or that people who end up following my blog find something of value from the content on my site.

The main point is that this record is something I own, I can make freely available, and can be accessed independent of algorithms that are meant to shape people’s attention. You can add this site to your RSS reader. Or you might stumble across a link to my thoughts in a social media algorithm.

The independence and accessibility of it is something that’s worthwhile, rather than keeping my thoughts locked up inside of LinkedIn or another closed ecosystem.

How to build a link blog

There are a number of ways to do this:

I build this website with Hugo, a simple static site generator. This means my content is mostly Markdown files on my laptop, which are turned to HTML, and I can move from host to host. The only costs are hosting (negligible to free) and the domain name/DNS. There’s a bit of a learning curve, but on the whole a curious, intelligent person can create their own site easily.
- If you are a developer you may want to pivot to a SSG that uses a language you are familiar with. Jekyll, Astro, Pelican, are all strong alternatives and there’s many more out there.
If you want a less hands-on experience, I strongly recommend Ghost. Ghost is a service for publishing newsletters and blogs. Like Substack, without some of the complicated politics.
WordPress is a bit more of a traditional blogging engine, though I feel like the ecosystem can be overwhelming at first, you might be interested in this if you are a more visual person.

What I like about Hugo is my ability to control and tweak many aspects of this site, while keeping the costs low. Aside from the domain name, with the amount of traffic I receive, the cost of my personal website is pretty much negligible.

If you’re interested in doing something similar, the broad steps are to:

Experiment with building a Hugo site on your computer, choose a theme that supports blogging, and get a working mockup together.
Purchase a domain name — this article from Cloudflare goes into this topic in detail.
Configure a hosting service and transfer your site to that hosting service. Here’s Hugo’s walkthrough on how to do this with Github Pages.
Map the DNS records for your domain name to your hosting service (Here’s a tutorial from Github Pages).

Details will vary based on your service providers, so please take these steps as a rough guide. Ultimately, once you’ve got the hang of deploying your site, it’s a good feeling, and you’ll be able to build your own little pocket of thoughts on the internet, making it a better place for everyone.

Dropout: Keep the Internet Weird

Tue, 23 Sep 2025 00:00:00 +0000

My TV watching habits have changed pretty dramatically with the times. I still love shows like NBC’s Hannibal—dark, aesthetic, dramatic. But more often than not, I find myself reaching for something a bit more lighthearted and fun. I’m nerdy. I’m a millennial. In short, I’m the target audience of dropout.tv.

Depending on your interests, you might have been exposed to Dropout from one of the short social media clips that make their way around various services. Or you might have been exposed to it through Dimension20, if you’re the sort of person who plays or is into Dungeons and Dragons. Either way, this is the sort of niche streaming service that provides me with lighthearted bits of skilled comedians and improvisers doing their thing. It’s been one of the subscriptions that I don’t regret in the slightest.

Ownership and advertising revenue

You might, if you’re the sort of person who’s been into internet comedy long enough, recognize a number of the comedians from CollegeHumor. Dropout has had an interesting history as a business — being given the freedom to pursue it’s own direction after acquisition by private equity. And it’s current trajectory makes it compelling as an alternative to other streaming services. Here’s an insightful conversation with Sam Reich, the current CEO of Dropout on the history and trajectory of Dropout:

Dropout was a priority that came out of IAC, which was our corporate parent at the time.

This was who owned CollegeHumor?

This is who owned CollegeHumor, and for years and years, IAC was trying to figure out how we would make not just a lot of money, but a lot, a lot of money. And there was always kind of a… A cynic might call it a get-rich-quick scheme at the time. It was ad sales, and then social media took a big chomp out of ad sales, and then it was television. It turned out television production didn’t scale very effectively. And then finally, the idea was, let’s try going direct-to-audience.

Just to go over-the-top, as they say. I’m not sure exactly what the top we’re going over is, but we’re going over the top of something. I guess the whole system.

That phrase makes it feel like we’re gambling the house, and in a way, we were. There was a collection of executives who were very bullish about this within CollegeHumor. I wasn’t necessarily one of them. I slowly but surely warmed up to it, imagining that if it didn’t work, at least we’d get to create our own cool stuff for a while. The notion was to go direct-to-audience. There won’t be the gatekeepers that there are in Hollywood. We won’t have to start over every year like we do in ad sales. That is, by the way, one of the intrinsic benefits of subscription: you’re not starting your business over every year, versus ad sales, where you have to go out and sell every year.

Rewilding the Internet

The conversation covers the history, the business model, the platform they use for streaming and some interesting speculation about what they’re doing right. One thing that particularly struck me was the reference to Homestar Runner, later on in the interview:

Interesting. Is there, on the list of reasons that you like this or want to do this, we talked about this before, but let’s end here with this. Is [the idea] that people aren’t doing things weird enough, and you want to do things weird, on that list?

One hundred percent. You and I have connected a lot on the topic of Homestar Runner over the years. Homestar Runner may be hugely responsible for my career taking the direction it has. It was incredibly influential on me. And something I loved about it was like, it felt like a walled garden of weird that existed at a URL.

Yeah. That resonates.

And I think about how sometimes I wish that I could plant a forest full of weird trees on the internet. I wish that the internet were still a place where, just like there was really fun, mysterious, hopeful stuff that existed a URL away. I would hope that Dropout can just be one of those things.

That shared sense of weird is also part of why I’m very into what they’re doing with Dropout. But more importantly, it echoes a vision of the internet that I hope we can reclaim. This essay by Maria Ferrell and Robin Berjon talks a bit about how the internet would function better if we would rewild it. Encourage an ecosystem where individual creators can build and share information freely, independent of particular platforms.

One thing that gives me hope is that the same tools I use to build gardens of docs make publishing a blog relatively easy and painless. What’s interesting to see from this piece is how platforms like Vimeo OTT give them the freedom to build their own subscription services for comedy streaming, independent of dependency on ad revenues. It’ll be interesting to see how technologies like atproto can help facilitate cultivating your own ecosystems further.

Self-Advocacy for Technical Writers

Fri, 19 Sep 2025 00:00:00 +0000

One of the things that has surprised me most in my career was the extent to which you may need to advocate for your skills and the utility of your profession within a changing workplace. As a technical writer, it’s easy to say you produce documentation, but “documentation” is a word that means many different things to different people.

Ideally, you have a manager with a clear vision of the work you can produce, strong quarterly goals, and adequate tooling. But that isn’t always the case.

Here’s a story that truly drove home the need to advocate for your profession.

That sinking feeling

“You’re going to have a lot more technical writing like that to look forward to.”

A senior leader said this to me, probably intending to be reassuring. To be honest, I had a sinking feeling in my stomach. I had just spent time working closely with a product manager on a lengthy proposal for a new architectural project. My work included articulating the proposed solution, modeling costs and ROI, and helping to identify potential risks.

The unfortunate thing is that this isn’t what technical writers typically do—in fact, it’s almost the exact opposite. I was helping someone write about what a system could or would be like. Technical writers are trained to dive into how systems work, providing instructions for how to use those systems to achieve specific goals. In manufacturing or hardware, we produce user manuals. In software, we produce the content that ends up on websites like Stripe’s documentation site or MongoDB’s Docs.

Software technical writers are, to borrow a term from Fabrizio Ferri Benedetti, devlings—technically minded people who are interested in and capable of figuring out how a product works to create web-based content that helps users understand it.

The document I was working on was the sort of thing that product managers and business analysts produce. I was happy to contribute because I wanted to be a team player, but that senior leader’s statement drove home something I believe every junior technical writer needs to understand, especially if they are the first or only technical writer at a small company.

Documentation is polysemous. Different people mean different things when they use the word.

Engineers are expected to produce documentation. Managers are expected to produce process documentation. If your company undergoes a SOC audit, controls will need to have documentation. Project leads? They have to produce documentation. One of the unfortunate truths about working in a knowledge-based company is that just about everyone has to produce documentation and they’d much rather be doing the “real work” instead of writing. Support teams are a great source of knowledge, but ideally, they’re turning that knowledge into documentation, too.

It’s not malicious. People will simply see you as a resource to help with their specific documentation needs. You will need to defend your own projects and territory, because in most scenarios, you’ll be at capacity trying to produce and maintain end-user documentation for your company’s products.

Why not draw the line?

If project documentation is a skill and responsibility for other departments, and you’re already quite busy with your core responsibilities, why would you want to help with that kind of project?

In my case, I was having trouble getting authorization for the projects I really envisioned. We were a team in transition. But the main reason was to try and steer the team toward a more mature workflow: it was nice to see a project take the shape of what I would call project documentation.

Project documentation includes things like:

Business Requirement Document (BRD): Outlines the business goals for a project, typically for stakeholders.
Product Requirements Document (PRD): Defines features and functionality for developers and designers.
User stories: Simple, short descriptions of a feature from the end user’s perspective.
User personas: Descriptions of target users, including goals and pain points.
Architectural Decision Records (ADRs): Documents the “why” behind key design choices.
Technical/System Design Documents (TDD/SDD): A blueprint of components, data models, APIs, or technologies for developers and architects.
Project Charters: Captures who authorized the project, high-level goals, key stakeholders, and project boundaries.
Project Plans: Outlines the scope, timeline, budget, and resources.
Risk Registers: Details potential risks, their impact, and mitigation strategies.
Decision Logs: A record of key project decisions.

I’m definitely capable of contributing to these kinds of documents. I’ve framed personas and user stories in situations where that information was tacit knowledge shared among the team members who designed and implemented a system. I’ve also written project charters, plans, and risk registers for my own projects.

The problem is that most of these documents require a kind of knowledge and involvement that a technical writer lacks. In an ideal world, I’m relying on PRDs, ADRs, and TDDs to write my documentation. The more these documents exist before a product is built, the more knowledge I have when I interact with the released product.

I think one of the unfortunate consequences of Agile escaping into broader business culture is that these kinds of documents are seen as unnecessary steps. This happens when teams forget about the word “comprehensive” and fail to pay attention to the many meanings of “documentation.” Agile was a response to attempts to comprehensively scope out entire projects and rigidly adhere to waterfall schedules. The right attitude is to have “just enough documentation,” and some complex projects require writing to get your ideas on a page.

The core of design, product, and project work is envisioning a future state. To ensure alignment, you need to communicate it. By building a culture where we had clear examples of early-stage documents and working closely with team members to build them, I hoped to help institute a cultural shift that prioritized reasonable product documentation.

This is a bit of an aside: I think one of the shifts with GenAI is that these kinds of docs are starting to fall away. I don’t mean to imply they’re all necessary, but I do think some record of design decisions is necessary once a project hits a certain level of complexity. The interesting thing is negotiating what this looks like with the existing team culture and new tools.

Self-advocacy

I’m not opposed to working in a lone-writer environment. There are lots of things that are exciting and invigorating about these kinds of companies. But there are a lot of competing demands, and you cannot rely on leadership to understand your skills and contributions. This is even true in cases where you work embedded in a team.

For this reason, having a game plan for self-advocacy is crucial. If you’re a technical writer like me, this probably doesn’t come naturally. The idea of self-advocacy can feel like selling or bragging, which I’m personally uncomfortable with. Here are some steps I’ve committed to that help me advocate for my work in a way that feels authentic and comfortable.

One thing I plan on doing is using the words “documentation” or “docs” less when I describe my contributions. As much as I love Write the Docs as a community, “documentation” has too many possible interpretations. Terms like “feature-specific user guides,” “API references,” “installation guides,” and “quick starts” are all much clearer.

Here are a couple of things I plan on striving to do, whenever I join a company:

Build a strong, shared understanding of my role with my immediate manager and create a plan for how I can be assigned work. Having a sample process document that you can adapt to new environments is a great conversation starter.
Find a time and way to introduce myself and my expertise. It may be a short presentation explaining what skills I bring, what kinds of work I’ve done, and my process for working with other teams. This helps set up guardrails and channels for incoming work. It’s also important to build relationships with key customer-facing teams in addition to your developer and product management teams. Most importantly, this presentation will emphasize the value of product docs for all roles in the company. If product documentation explains what and how are product works, it is a helpful knowledge resource for marketing and sales. If this isn’t an opportunity, I’ll build my own profile in Confluence or SharePoint, so that people can understand my perspective and skills.
Be engaged and champion our content in Slack/Basecamp/Discord. I’ve been in situations where people have asked questions like, “What are the differences between these three features/products?” in our group chat. It’s a good question that points to a confusing area in our product, and I think they genuinely didn’t know that good documentation sites can help resolve those kinds of questions. By answering these questions and championing your site, you’re increasing the visibility of your work.
Celebrate contributors. Knowledge is a shared enterprise. Building relationships and celebrating team members who take to the time to give you good feedback is important for driving adoption of your work within the company. By expressing gratitude and value for colleagues who contribute feedback, you can build a culture where leadership acknowledges the value of your work.
Maintain a log of my wins and lessons.. I try to keep daily notes on my work. It’s important to round these up into wins and lessons. It’ll help when I meet with managers to talk about my work. Along with that, find a way to measure outcomes by collaborating with support and other customer facing teams.
Show up for engineers and PMs. These teams are the core of what I do. While I’m building advocacy and learning, it’s important to collaborate and work with the engineers who build the products I’m writing about.

This is a starting point, but these commitments build a practice of self-advocacy that doesn’t feel like bragging. They help build recognition for your work beyond your immediate team and foster a culture where your contributions are understood and valued.

Kuba Suder: Introduction to AT Protocol

Tue, 26 Aug 2025 00:00:00 +0000

If you’ve been interested in understanding the world of Bluesky and AT Proto, Kuba Suder has been writing excellent blog posts. I’ll be following along closely, since I think that algorithmic choice is going to be an extremely important feature of any social media framework that I would want to use.

A Complete Guide to Bluesky serves as an introduction to Bluesky, as an app:

But that’s just the tip of the iceberg. Bluesky has built a system where anyone with a server and some knowledge of coding can implement their own algorithmic feeds that they can share with everyone else. There are currently about 40 thousands custom feeds (as of Feb 2024) made by the Bluesky community that you can add to your app. And more importantly, the “Following” and “Discover” feeds are just what you start with by default – you can set any of the thousands of other feeds as your main feed, and you can even remove the two built-in feeds if you don’t like them, and leave e.g. only the “Cat Pics” custom feed as your only feed tab. Nothing here is forced on you.

This is from the section on feeds, but I think the sections on safety and moderation, and features like starter packs are helpful if you’re looking to understand Bluesky.

More interesting is his recent post Introduction to AT Protocol. For someone interested in the technical workings of the world behind Bluesky, this is a great introductory post:

The system they’ve built, of which Bluesky was initially meant to be just a tech demo, is called the Authenticated Transfer Protocol, or AT Protocol, or ATProto. Bluesky is built on ATProto, and it is in practice a huge part of what ATProto currently is, which makes the boundary between Bluesky and non-Bluesky a bit hard to define at times, but it’s still only a subset of it.

Bluesky in this second meaning is some nebulous thing that consists of: the data types (“lexicons”) that are specific to the Bluesky microblogging aspect of ATProto, like Bluesky posts or follows; the APIs for handling them and for accessing other Bluesky-specific features; the rules according to which they all work together; and the whole “social layer” that is created out of all of this, the virtual “place” – the thing that people have in mind when they say “this website”, even when it’s accessed through a mobile app. One of the coolest things about Bluesky & ATProto, in my opinion, is that it connects many different independent pieces into something that still feels like one shared virtual space.

People outside the company can create (and are creating) other such things on ATProto that aren’t necessarily Bluesky-related – see e.g. WhiteWind or Leaflet (blogging platforms), Tangled (GitHub alternative), Frontpage (Hacker News style link aggregator), or Grain (photo sharing site). They use the same underlying mechanisms that are at the base of ATProto, but use separate data types, have different rules, goals, and UIs.

The whole post serves as an excellent conceptual introduction to the world of ATProto. I’m curious about building some basic integrations from this website to bluesky and the Fediverse, and will be making reference to this post (and subsequent ones in the series!) as I start to explore.

Drew Bruenig on Reasoning Models and Chain of Thought

Mon, 21 Apr 2025 00:00:00 +0000

Here’s an excellent post on “reasoning” and “chain of thought” models by Drew Bruenig: What We Mean When We say “Think”. It provides a history, and description of how these pieces of technology function, and makes predictions about how certain kinds of testing will shape the perceptions of the utility of LLMs.

All in all, it’s a good read if you want to think carefully about this technology.

In particular, there’s a clear discussion of reinforcement learning (RL) and the economic factors that go into it both it’s application, which makes a pretty persuasive case for the following predictions:

Models will keep getting better at testable skills: Quantitive (sic) domains – like programming and math –– will continue to improve because we can use unit tests and other validation methods to create more synthetic data and perform more reinforcement learning. Qualitative chops and knowledge bank capabilities will be more difficult to address with synthetic data techniques and will suffer from a lack of new organic data.

An AI perception gap will emerge: Those who use AIs for programming will have a remarkably different view of AI than those who do not. The more your domain overlaps with testable synthetic data and RL, the more you will find AIs useful as an intern. This perception gap will cloud our discussions.

I’m inclined to agree - LLMs function significantly better in some areas than others and it’s likely to only intensify.

What Makes a Good Technology

Sun, 20 Apr 2025 00:00:00 +0000

This is a question I’ve been asking myself lately. It’s exciting to be living through the advent of what feels like a major technological change, but I feel like this isn’t a question we never really stop to think about. So much of our lives are immersed in technology and influenced by its creators. And pivoting from philosophy to a career in “tech” — by which society mostly means software these days, well, it leaves me feeling reflective.

I do know what kinds of enduring technologies exist that I love and I know what kinds of technologies exist that frustrate me. In my About page, I mention that I think that RSS, the bicycle and Wikipedia are examples of great technologies. I mean that in a normative (and moral) sense. They’re the sort of thing that I think are genuinely praiseworthy. So, let’s see what kind of a theory we can come up with to account for why.

What is technology?

This is our first stop. Did you expect anything different from someone who spent too much time in the philosophy room? I think how we answer this actually has important results for how we evaluate technologies.

Technologies, first off, are things that are produced, they’re the result of some kind of directed action.They also require the application of knowledge (whether explicit or implicit), in pursuit of achieving some kind of end. Technologies can be used for things other than their intended ends, but technologies have a functional goal that result from their standard application. Importantly, technologies also require that things be a certain sort of way in order for them to function. This is both social and material.

There’s a certain sort of weak normative force around technology. There is a sense that you should use it in certain ways that’s related to the original goals (e.g., you should hit a nail with the flat end of a hammer, not the claw, if you want to drive it in effectively). And technologies that are easy to use in that sort of way are good at what they do. This isn’t moral force, but technologies are forces for coordinating the world around us.

And it’s in that normative sense that I think we can evaluate technologies as good or bad on their own terms. This is a kind of functional goodness. It’s good for the task it was meant to be put to. We can also evaluate technologies in terms of the outcomes they are designed to produce and how they require us to organize materials and people (both of these are moral evaluations). A technology is organized towards achieving some kind of goal and it’s good or bad in terms of both the nature of the goal and in terms of how well/easily it facilitates achieving that goal. It’s genuinely important to evaluate technologies in terms of both of these parameters.

For example, license plate reader cameras are a remarkably effective technology in terms of the functional achievement of their goal. They enable the vast collection of data, the coordination of those datasets, and access to that data by law enforcement organizations. But the construction of a surveillance state is not a laudatory goal, as it is vulnerable to abuses by bad actors such as this officer who used it to stalk an ex-girlfriend. So I think we can use both senses when evaluating technologies.

But I don’t want to focus on bad technologies. I think that it’s more powerful if technologists (people who care about and deploy technology) have a sense of what good technologies are and use that to shape and coordinate their efforts. And it’s important to have these discussions so that we can evaluate new and emerging technologies and systems.

Good tech

The bicycle

Let’s start with the bicycle. Bicycles might seem a little weird to include in my understanding of technology, after all, this started with my reflections on software, right?

Bicycles have been around since the 19th century in various forms. The functional goal of the bicycle is to convey a person using two wheels, and the mechanical effort of the rider, translated through pedals. This goal - transporting a person, is pretty excellent. It allows them to achieve a variety of other goals in reduced time. It can also be recreational and social. So on the whole, the bicycle passes the goal check.

But how well do they achieve this goal? Well, this is an interesting point - because it depends on the bicycle and the conditions you find yourself in. It’s why we see so many different forms. My single speed road bike excels in flat urban environments. A downhill mountain bike with full suspension and knobbly tires could go places that my commuter could never do that. Both scenarios require a bit of expertise to use, and also the presence of certain kinds of infrastructure.

I think it’s important to note though, that the idea of a bicycle imposes very few costs or burdens on the world around it. In many ways, bicycles easily fit with the rest of our social and technological fabric. It doesn’t generate pollution and only requires me to eat and stay healthy to operate. With a few basic tools and parts, I can perform most of the maintenance my bicycle needs. This is an important part of why I think that it’s a good technology — it requires spaces where I can operate it (though those are mostly spaces that exist) and minimal upkeep that I can provide by myself.

There are some drawbacks however: manufacturers have specialized parts so the supply chain might not always be available. And I may be sweaty when I arrive at my destination. And it’s not a great means of conveyance for larger distances and using it in the winter is a bit of a hardship. But for getting groceries, a short commuting, or popping over to a coffee shop? It’s much better than a car.

I’ve had my bicycle for more than decade, and it was purchased used. It takes me all kinds of places. It’s fun, it’s relaxing, it’s reliable. It’s the sort of thing where I’m considering get another specialized bicycle so that I could ride more in harder conditions. It’s a good technology.

Wikipedia

Wikipedia is interesting — the technology is built for the communal aggregation of knowledge. It’s a database and a front end that comes together to produce a website where anyone can functionally contribute knowledge. If it was just that, though, it’d be a horrible mess of edit wars and chaos. It’s also an organization, and a scheme of processes about how to make those contributions. It’s that social coordination through norms that makes it relatively successful.

People can attempt to coopt and influence it, but if a company attempts to use it for marketing purposes, these processes attempt to shove the whole enterprise back on to the rails. Strong norms regarding citations and point-of-view in authorship make it an excellent place to conduct initial research on a topic, pointing you to primary resources that can be the basis for successful direct research. In many ways, it’s the perfect secondary source to get you started, even if it’s a little messy at times.

Because Wikipedia is a collection of open knowledge, the practices, standards, and what is done on it, are all transparent. That’s how it builds it’s trust. It’s kind of remarkable that these are the things that the blockchain is supposed to provide. In part, I think this is because of the social goals behind both technologies, and that Wikipedia functions because of the ease and transparency of contributions. So, I think that Wikipedia is a great example of how the social dimensions of the technology work to set a standard.

It’s also not perfect. Standards and practices can vary within communities inside of the contributor culture. Learning and understanding Wikipedian culture and terms is a process. And low priority articles can tend to be messy. But it’s a genuinely impressive and vast collection of knowledge that is freely accessible on the internet, maintained by a non-profit and volunteers. It’s an astounding achievement of people coordinating effort, software, and practices to produce an objectively valuable resource.

RSS

I feel like folks who might find their way to my blog are familiar with RSS. It stands for really simple syndication. I feel like this is probably a little contentious as a candidate for inclusion, since it’s probably a thing that most people thought died out as blogs went out of fashion.

Here’s the basic idea behind RSS. If I publish a stream of content to the internet (say blog posts, podcast episodes, videos, etc.) I can have a single file on my website that summarizes the posts into a feed. People who would like to access the feed can use programs that are built to interpret that standard and consume the feed on their own devices.

So if you use a podcast aggregator, then there’s a pretty good chance that you use RSS. As someone who writes a blog, complete with an RSS feed, it’s easy to set up and configure, and when I publish changes to my website, the RSS feed updates automatically. So it’s pretty great from an author perspective.

From the perspective of someone consuming writing or podcasts, a feed aggregator/reader is a powerful tool. I can control how my tool presents content to me - and I have a chronological feed of posts from a range of sources. I can choose to bulk skip posts from particular aggressive publishers. It offers me a great deal of control about how I receive what you put out.

Why did these fade away? A big reason is that open content and advertising weren’t served by this mode of content delivery. And social networks began to provide streamlined, high engagement content. But I think that podcasts have been so viable shows that there’s ways to deliver content regularly. RSS is also a bit of a mess: as a standard it’s difficult to enforce, and different websites may use different versions of the feed. It’s an old standard that faces the difficult problem of being superseded by a new standard. It’s also difficult to monetize.

But the idea of integration of feeds is alive and well, and I think quite exciting in the ideas behind federated social media at Mastodon and Bluesky. Podcasts are a great reminder as to why this technology is great: enabling you to control the algorithm and build your own collections of media. So I’m optimistic for things to come, and will point to RSS as a powerful form of one-to-many communication.

Concluding thoughts

So, I’ve discussed a bunch of technologies and what makes them good or bad technologies. I think that we should celebrate good technologies. And that identifying them involves thinking about the goals they achieve, how we use them to achieve those goals, and what kinds of demands they make on the world. We live in an era where people are enthusiastic about technology because it enables us to do things (yes, the subtext is large language models/generative AI). Stepping back though, I think it’s important to be careful to think about how a technology works, what it requires of the world, and what it produces.

It’s important not just for personal or political reasons, but that as a worker and user of technology, having a framework for thinking about whether what I’m building or using is good is valuable professionally. For example — does it make sense to use an LLM for feedback over a linter? Or are there combinations that might be effective?

I’m going to use this reflection as a bit of a kick-off. I’ve been interested in critically thinking about technology for a while, but a 2023 interview with Meredith Whittaker tipped me off to the work of [Ursula Franklin]. In 1989, she gave the CBC Massey Lectures — which were collected into The Real World of Technology. Here’s what Whittaker has to say about Franklin’s lectures:

…an incredibly clear-eyed view of the dangers of social control related to computational technology, networking, database, and the early visions of what would become the Internet that were emerging around that time.

This early vision for the commercial internet, the idea that we would connect every computer to every other computer and this would create social benefit and economic benefit, looks strikingly similar to the promises being made today. If you read back to the primary documents you’re looking at incredibly familiar imaginaries: Health care is always available, education is free, all the world’s information is free. The promises haven’t changed, just the configuration of our social and economic lives. Her book was clear-eyed about some of these dangers, and very clear-eyed about how the information asymmetries that this technology would create could be used for social control.

As I read through it, I’ll post some of my thoughts to this blog. I think it’ll be interesting to chart the progress and if my views change as I work through it. I’ll post reflections chapter by chapter, and I’m looking forward to getting started.

suitenumerique/docs: An Open-Source Alternative to Notion

Tue, 18 Mar 2025 00:00:00 +0000

Docs (GitHub) is an open source alternative to Notion/Google Docs being built by the French and German governments (with the Netherlands being onboarded). This is exactly the sort of work I like to see coming out of governments.

Crucially, this application can be self-hosted. Given our current political landscape, digital sovereignty is going to become significantly more important. What I like about this, however, is the recognition that investment into infrastructure that can provide for tangible benefits for government can also become a common good.

In Canada, we have a collection of government projects available as open source. Celebrating and discussing the value from these projects is something our societies should do more.

A Simple Flesch-Kincaid Calculator for Markdown

Sun, 09 Mar 2025 00:00:00 +0000

This is a quick post inspired by a situation that someone posted about on r/TechnicalWriting. A technical writer is working as a contractor, needed to evaluate the readability of their content, but was limited in terms of the tools that they could acquire due to strict security and confidentiality requirements.

At first glance, assessing how hard it is to read a text is a matter of semantics — what’s going on in terms of the ideas conveyed by the words and the way the sentences work to convey meaning. But, well, in English, syntactic features (how the units of words and sentences are constructed) aren’t that bad of a proxy for estimating the overall difficulty of a text.

While there are tools like Hemmingway out there, I also believe that it’s pretty empowering to know a bit of Python so you can build your own library of scripts and tools to work with files on your own.

Flesch-Kincaid readability tests

The Flesch-Kincaid readability tests are a pair of measures of reading difficulty that rely on two measures: average sentence length (ASL) and average syllables per word (ASW). There are two tests: the reading ease test and the grade level score. Interesting bit of history here: this emerged as a standard for the US military, and spread into industry from there. Eventually, these scores were built into Grammarly, MS Word, etc. With this proxy, we can easily implement the calculator.

We can start by noting the two formulae that we’ll use. The reading ease-score is calculated with the following formula:

Score = 206.835 - (1.015 * ASL) - (84.6 * ASW)

In this case, a higher score is more readable.

The grade level score is calculated with the following formula:

Grade level = (0.39 * ASL) + (11.8 * ASW) - 15.59

The value is roughly the school grade level that would be expected to comprehend this passage. Since this is a mechanical test, it’s actually baked into law: insurance contracts in many states are required to be written at a specific grade level.

There are some key assumptions here: average word and average sentence length doesn’t necessarily indicate semantic complexity and it completely ignores elements like sentence structure. But it gives us a handy first pass. Let’s turn this into a python script that can take a raw Markdown file and return the corresponding scores.

Planning

A Markdown file contains simple syntax to indicate formatting. Since I also use Markdown primarily with static site generators or Obsidian, the overall structure will be:

Take a Markdown file as an argument and store the text in a string.
Use regular expressions and the substitute function to strip any formatting elements.
Parse the text to build lists of sentences and words in the text.
Loop through the list of words and count the total number of syllables.
Perform and return the calculations.

When implementing this, you’ll want to think about the kinds of source documents your parsing. Both Hugo and Obsidian include front matter specified as YAML or TOML, since I don’t want the front-matter contributing to the score of the text, I’ll need to handle that front matter in addition to formatting or other elements of Markdown.

Implementation

I started with a simple method to read the file and return the text. When a user runs the script, they’ll be prompted to specify the path to the file:

def calculate_Markdown_flesch_kincaid(Markdown_file_path):
    """Calculates Flesch-Kincaid score from a Markdown file."""
    try:
        with open(Markdown_file_path, 'r', encoding='utf-8') as file:
            Markdown_content = file.read()
            return calculate_flesch_kincaid(Markdown_content)
    except FileNotFoundError:
        return "File not found.", None
    except Exception as e:
        return f"An error occurred: {e}", None

if __name__ == "__main__":
    Markdown_file = input("Enter the path to your Markdown file: ")
    score, grade = calculate_Markdown_flesch_kincaid(Markdown_file)
    if score is not None:
        print(f"Flesch-Kincaid Score: {score:.2f}")
        print(f"Equivalent Grade Level: {grade}")
    else:
        print(score) #print error message.

Now I just need the method to handle cleaning the file and calculating the scores — calculate_flesch_kincaid.

Cleaning the file

Honestly, I dislike writing regex. When I was learning Python, the courses on regex and string handling were the ones that struggled to hold my attention the most. So, I think this is something that generative AI is genuinely useful for (while I have complex feelings about generative AI, I’m fine with this). To handle the text conversion, I specified the basic syntax of Markdown and prompted the Gemini to specify regex to identify key patterns of characters and remove them. This returned the following series of text = re.sub(r'expression', '', text) lines to convert the file to simplified text for analysis.

I wanted to use the script with Hugo and Obsidian, so I added blocks to perform a similar operation for shortcodes and YAML/TOML front matter:

# Remove front matter (YAML or TOML)
text = re.sub(r'(^---.*?---)|(^\+\+\+.*?\+\+\+)', '', text, flags=re.DOTALL)

# Remove Hugo shortcodes
text = re.sub(r'\{\{<.*?\}\}\>', '', text)
text = re.sub(r'\{\{%.*?%\}\}', '', text)

# Remove Markdown formatting
text = re.sub(r'#{1,6} ', '', text)  # Remove headings
text = re.sub(r'\[.*?\]\(.*?\)', '', text) # Remove links
text = re.sub(r'\!\[.*?\]\(.*?\)', '', text) # Remove images
text = re.sub(r'`.*?`', '', text) #remove inline code
text = re.sub(r'```.*?```', '', text, flags=re.DOTALL) #remove code blocks
text = re.sub(r'\*\*\*|\*\*|\*', '',text) #remove bold and italic
text = re.sub(r'---', '', text) #remove horizontal rules
text = re.sub(r'^>.*$', '', text, flags=re.MULTILINE) #remove blockquotes
text = re.sub(r'~~.*?~~', '', text) #remove strikethrough

text = re.sub(r'[^\w\s\.\?\!\,\:\;]', '', text) # Remove special characters except punctuation
text = re.sub(r'\s+', ' ', text).strip() # Remove extra spaces

A bit of an aside — the initial text handling logic was pretty good, but the way it initially handled the front matter introduced a bug where it was returning null strings. Having a couple of test files as you go can pay off! Basically the test file included a lorem ipsum block and I could add in blocks for any category that needed to be handled by the cleaning.

After substitution, I added a quick check to ensure that the text string is not empty, stopping the script if it is and returning an error message. Following processing, we need to access both the words and sentences from the Markdown file, so I defined two lists: words and sentences. Sentences is the list that you get by splitting on sentence ending punctuation (., !, and ?), and to get the words, you can use the simple regex expression \b\w+\b.

sentences = re.split(r'[.!?]+', text)
sentences = [s.strip() for s in sentences if s.strip()]

words = re.findall(r'\b\w+\b', text.lower())

syllable_count = 0

With these two lists in hand, we have everything we need to count syllables and calculate the scores.

Calculations

Accurately counting syllables in English is actually a pretty complicated task and context dependent, but we can use spelling to make a quick and reasonable estimate. From Grammarly, they recommend counting the total number of vowels, then subtracting silent vowels (e.g., vowels that occur in tuples, the letter e at the end of a word, etc.). This is pretty easy to set up a pair of nested loops, going through each word and each character in the word, increasing the number of vowels only if the previous character wasn’t a vowel. If the last character is an ’e’, we’ll subtract one from the final count.

Without any additional steps, this will slightly under estimate the number of syllables. Words ending with an “e” often don’t introduce a new syllable (e.g., ‘ice’ is monosyllabic), but in some cases, they do (as in “ukulele”). Since the way I looped through counts vowels, I can add an if statement to check if the word ends in an ’e’ and decrease the count. In the “ukulele” case, the pattern is complicated. “Ale” is monosyllabic, and “simple” only has two syllables. Basically, the thought is that in longer words, with a vowel sound before the “-le” you have an extra syllable (e.g., “allele”, “ukulele”). So we’ll check for that pattern (ends in “le”, word length is greater than 3 letters, and third last character is not a vowel).

Here’s how the script handles counting syllables:

syllable_count = 0
for word in words:
    vowels = "aeiouy"
    word_syllable_count = 0
    prev_char_was_vowel = False
    for char in word:
        if char in vowels:
            if not prev_char_was_vowel:
                word_syllable_count += 1
                prev_char_was_vowel = True
            else:
                prev_char_was_vowel = False
        if word.endswith("e"):
            word_syllable_count -= 1
        if word.endswith("le") and len(word) > 3 and word[-3] not in vowels:
            word_syllable_count += 1
        word_syllable_count = max(1, word_syllable_count)  # Ensure at least 1 syllable
        syllable_count += word_syllable_count

    num_sentences = len(sentences)
    num_words = len(words)

Now that we have all the values for our formulas, it’s a simple matter of implementing and returning the results:

    num_sentences = len(sentences)
    num_words = len(words)

    if num_sentences == 0 or num_words == 0:
        return "Cannot calculate score: Insufficient text.", None

    average_sentence_length = num_words / num_sentences
    average_syllables_per_word = syllable_count / num_words

    flesch_kincaid_score = 206.835 - 1.015 * average_sentence_length - 84.6 * average_syllables_per_word
    grade_level = round(0.39 * average_sentence_length + 11.8 * average_syllables_per_word - 15.59)

    return flesch_kincaid_score, grade_level

Conclusion

With the pieces in place, it’s pretty simple to run: you run the script and enter the filepath for the Markdown file that you’d like to analyze. It handles my blog posts with ease and isn’t a bad heuristic to evaluate the readability of the piece of writing that you’re working on. This is a nice little addition to my drawer of helper scripts for writing projects. Not bad for a quick side project!

Meredith Whittaker on Privacy and Signal at SXSW

Sun, 09 Mar 2025 00:00:00 +0000

There’s a lot of great insights in this talk with Meredith Whittaker at SXSW. It’s refreshing to see someone talk so straightforwardly about privacy and the incentives that shape our current notions of innovation and progress:

I particularly like how she articulates why we should care about privacy:

Look, everyone’s always had something to hide… you all close your bathroom door, right? You talk to your best friend in your moments of crisis. The same way you talk to your boss. Do you think out loud when you’re working through an idea. Do you tell your new friend you met at a bar the same thing you tell your oncologist? No, no. We have different relationships. We have a need for intimacy. We have a need for safe spaces to think.

We have various relationships that are modulated in different ways with different people. And we have a world that is defined by various power asymmetries in which those in power can often weaponize or misuse intimate information about us, information about our preferences and our patterns and our relationships and our vulnerabilities. So there’s no world we have ever had, however many changes we’ve seen where people don’t care about privacy. However, we have made privacy into this sterile, bleached, technocratic concept that feels like we don’t have a stake in it. We don’t think about what are the things, the precious things, the democracy, freedom of thought, freedom of expression, intimacy that privacy actually guarantees as a fundamental condition.

There’s a clarity of purpose that really makes Signal stand out from other communication or social tools:

I want to contact my friends. I have a, you know, I want to relate to other people. And that’s like, I don’t I don’t pick my friends based on whether they care about privacy. I pick my friends, whether on whether they’re cool, you know, whether I like them, whether when I hang out with them, I want to keep hanging out with them or I want to go home. Right? Like. And and that’s the world we want to live in. Not one where you have a sort of, you know, it’s technological ideology leading, you know, our relationships.

And some good insight into the economic incentives that it takes to maintain a privacy focussed tool like Signal, as well as the kinds fo things that shape the development of tech:

…we’re looking at a landscape that’s a little bit perverse, frankly, where you have, you know, let’s give an example. Right. You have a like some defense tech startup is white labeling an AWS API and calling it innovation. And they’re getting billion dollar valuations and Signal is, you know, fundraising, even though it’s, you know, probably one of the most vital technologies used by every military in the world, right. So, you know, there is something deeply, deeply broken about the economic paradigm, about the incentives in tech.

And for now, what we’re doing is everything we can to protect what Signal is. Because if Signal, you know, if we shut down Signal today, we couldn’t rebuild it, right? You can’t rebuild a network effect in a saturated market. You can’t rebuild the gold standard reputation that has been developed day by day over a decade, by people inspecting our code, looking at our cryptographic systems, looking at what we do, improving it. There’s an ecosystem built around it that you can’t just snap your fingers and and do. And, you know, that’s one of one of the lessons around communication networks, right. The network effect is really powerful.

What I Work With: Tools for Technical Writing in 2025

Fri, 21 Feb 2025 00:00:00 +0000

I feel like technical writers are kind of a difficult creature to understand. Documentation is one of those words that means so many different things to so many different people, but primarily, we build written resources that explain how to use technical products. In my career, the technical products have been software. The audience for my writing has been admins, developers, or non-technical end-users. There are a number of ways to do this, ranging in appearance and complexity. Sometimes I work with documents in a way that looks like code or fiddle with template files for websites. Other times I work through a user interface designed for publishing to multiple endpoints. So I think it typically makes sense for technical writers to be flexible, understanding enough to work with different kinds of tools.

After all, we’re kind of generalists. We need to be able to understand how technical products work. And when you produce documentation, you should probably be pretty good at using documentation as well.

So, here’s a snapshot of my current setup. Maybe I’ll revisit this in five years! A quick caveat: if you prefer more user-friendly paid services, this DIY toolchain might not be your cup of tea!

Hardware

I use a Framework 13, equipped with an AMD Ryzen 7 CPU and Windows 11. It’s a pretty cool little laptop, but I wouldn’t recommend it for everyone. I’ll go into the pros and cons below. I’ve been debating dual-booting with Linux, but for app compatibility and ease of use reasons, I’ve stuck with Windows. When I need to use a Linux development environment, WSL2 is there. But more about that in my software section.

Over the years, I’ve used various laptops: MacBooks, Asus netbooks, and more. I enjoy exploring different operating systems and hardware, configuring tools to meet my needs. I’m someone who likes to fiddle with hardware and switch between environments. So what works for me might not work for you!

Pros

I love the Framework’s modularity with swappable expansion cards (HDMI on the left instead of the right? No problem!), privacy sliders for the microphone and webcam, and Linux support. I’m debating returning to desktop Linux depending on how Windows evolves. The matte screen is a bonus for productivity, reducing glare and has an excellent resolution. It is honestly pretty comfortable for blogging with Hugo running in server mode (for my editing flow) or comparing diffs in VS Code.

Battery life and CPU are perfect for what I need. It’s not spooky-great like Apple’s silicon, but the AMD Framework meets my needs for a day on the go.

What really draws me to it is that every component on the laptop can be upgraded or swapped out for repairs. If I find that media processing or development tasks require more memory than I have, I can order compatible sticks and do the upgrade myself. If the screen is damaged? That can be replaced.

While the ability to repair is dependent on the continued operation of the company, this is so radically different from every other laptop manufacturer that I think it’s worth supporting. This has been successful enough that Intel seems to be jumping on the bandwagon!

Cons

The modular IO ports can be finicky with the AMD mainboard. Where I put the USB-C and HDMI modules matter with the AMD mainboard. It doesn’t break my experience, but you do have to think about things.

The keyboard and trackpad are also misses for me. The keyboard is functional, but it’s not as good as the Macbook style scissor switches. There’s noticeable flex when typing. I also don’t love that f12 is mapped to launch the Framework marketplace by default (cat stomps can suddenly open a browser window). The trackpad isn’t on the same level as Macbook’s for gestures. But honestly, I use mine with a mouse more than the trackpad.

The build quality is a little middling - It’s not bad, but it’s not as sturdy or well put together as some of the alternatives in the price range. The hinges are a bit too easy to open, and bouncy train rides can be an issue.

I have noticed that in my current workflows, the 16GB of ram I configured it with isn’t quite enough. Having multiple apps open (Discord, Slack, VS Code, Front… etc.), and then trying to work with WSL2 gets a little dicey. Thankfully I can upgrade! But for building this site or other lightweight platforms, this machine works wonderfully.

Peripherals

A couple of other essential things:

An external monitor, I have a 32" 1440p display
A mechanical keyboard (I alternate between a Keychron K6 and a Keychron C3 Pro)
Logitech MX Anywhere mouse (for portability)
Steelseries over-ear headphones for long focus sessions or calls
A USB-C to HDMI, USB-C, and USB adapter
Leuchtturm 1917 notebook
Lamy Al Star loaded with black ink

Software

A software technical writer is responsible for producing written content to explain how software works. This is usually in the form of a help center or docs website. In other branches of technical writing, you may produce print or PDF manuals. I work with static site generators (SSGs), content management systems (CMSes), and learning management systems (LMSes) to produce and host content to explain how software works (including videos and screenshots). I think the choice of docs system really depends on how you envision your team functioning and who contributes to your documentation.

There are strong reasons to prefer docs-as-code as a methodology (using Git, SSGs, workflow automations, and tests) if you have a community of contributors who are comfortable with Git and markup languages. There are strong reasons to prefer a CMS if you have a community of users who are more comfortable working in what-you-see-is-what-you-get (WYSIWYG) type environments. While specialization and tool knowledge is valuable, it can pay to be a bit of a generalist.

For this site, I rely on Hugo, which is a static site generator, and a common tool for docs-as-code projects. Version control, revisions, and experimentation are all easy to handle using Git and Github. I write inside of VS Code, making use of extensions to handle spellcheck and syntax highlighting. It’s also easy to extend and support your docs-as-code projects with helper scripts and functions to carry out automations.

I run Vale, a linter (tool to check each blog post against a set of style rules), a python script to check links, and python script to move images to a folder I back up to Google Drive (saving me from backing up image files in Github). In my contract work, I can use this setup to build and test templates and configurations for CMSes and LMSes using Docker containers. This involves working a bit with Windows Subsystem for Linux (WSL), which has been a great way to have a flexible and customizable development environment in addition to the more stable Windows environment. Running WSL, Windows, and various productivity apps is where I feel the ram pinch a bit, but taking a bit of care to ensure I’ve properly configured the Docker and WSL has made things workable (along with minimizing the number of other apps I have open while I’m focussed on these tasks).

Here’s a summary of ones that I find particularly useful with an emphasis on free or open source options:

Category	Tool(s)	Notes
Operating System	Windows 11, WSL2	I chose this for its battery life and software compatibility. WSL2 allows access to a Linux environment if needed (e.g., with Docker)
Productivity & Utils	PowerToys (FancyZones, PowerRename, etc.)	This is essential for a Windows 11 user. Various handy utilities, worth it alone for bulk renaming of files.
Development	VS Code, Git, GitHub Desktop, Hugo, Pa11y, Vale, PowerShell, Python	VS Code is my primary code editor; Git and GitHub manage version control; Hugo is used for static site generation; Pa11y and Vale automate accessibility and style checks; PowerShell is the primary terminal.
Screenshots	ShareX	A powerful and configurable screenshot tool.
Video	OBS Studio, Kdenlive	OBS Studio is used for screen recording and streaming; Kdenlive is used for video editing.
Audio	Audacity	Used for audio recording and editing.
Command Line	Chocolatey, ImageMagick, Pandoc, etc.	Chocolatey is a package manager; ImageMagick and Pandoc are used for image and document manipulation, respectively.
Browser	Chrome, Firefox, Edge	Multiple browsers are used for different workflows and testing.
Note-Taking	Obsidian	Used for its linking, search, and knowledge graph features, useful for drafting and managing content in various formats (Markdown easily transfers to Hugo projects, Google Docs). Joplin or Logseq is an alternative.

I am purposefully leaving off an AI tool. There is a range of these available, and most of them will work well for general queries and editing, within reason. All of the major providers support adding materials and files as context. The important thing is that they aren’t essential for my kind of workflow and many of them are functionally interchangeable. If you are working as a contractor, it’s also important to meet requirements from the company you are contracting with, so keep in mind confidentiality and security.

Final thoughts

I think that this is a pretty powerful web-publishing tool set and you can work through this with fairly minimal licensing fees — Obsidian requires a license if you are using it for commercial purposes, but everything else (aside from Windows), is freely available. I also feel that I could adapt this toolchain to Desktop Linux or MacOS with fairly minimal changes, which means it’d be flexible enough for any company I’d be going to work with. The repairability of my laptop also means that I can keep it going in the event of a hardware malfunction, but so far the Framework has been stable and powerful.

It will be interesting to see how I feel about the Framework in five years, and whether I’ve done a modular upgrade. My last personal laptop was a Macbook Pro that I used for more than a decade. I’m feeling confident that this tool chain will work well into the future.

Replacing Facebook: Fb to Obsidian

Sat, 15 Feb 2025 00:00:00 +0000

One of my goals for 2025 is to remove my dependency on social media. I previously discussed how I was staying on top of local news and events without relying on a platform like Facebook. As a Canadian, Facebook stopped being an effective news platform after Meta decided to remove any linked content to Canadian news providers following the Online News Act (Bill C-18). This left Facebook’s function in my life as a way to stay connected to friends and contacts.

As a social network, Facebook is effectively a record of the people I’ve connected with over time. It also supports two primary ways of communicating with people in my social network. The first is one-to-many: I can make a post that other people can read, if they encounter the post in their feed. They can then comment on the post, and it can begin to foster a conversation. The fundamental problem is that one-to-many communication in this mode is entirely dependent on the algorithm’s feed. The other main mode of communication is one-to-one. With the messenger app, you can reach other people directly and exchange messages.

And yes, I know that Facebook has some other things going for it — games, marketplace, videos, community groups etc. Those are secondary features. Social connections and communication features are the primary draws.

If that’s what Facebook is supposed to do, what’s keeping me from using it?

As a recipient of one-to-many communication, it just doesn’t work. At my last count, I see at least six posts from things I do not want to see for every one post from a friend. This is too much waste to wade through and then it’s for things which are algorithmically suggested. There’s no guarantee that what appears will be what I want to see. And these odds make me less willing to put out updates for people in my life who I want to see things that are going on with me.

So, I got to thinking about what I need, and how to replace Facebook in my life. This blog post details the process, and what I’ve done to regain a bit of control over the information.

Replacing feeds

There are two ways out of feeds that I can see: for smaller clusters of people that I want to talk with or share general life updates, I use group chats. It’s free from the clutter and competition on Facebook, and facilitates just as much group communication as the post. Chat rooms and forums allow you to focus on topics or commonalities, and so I’m more engaged in Discord and Slack servers. It turns out that social media became too big and messy, and so we’ve retreated to communities where we can control the intrusive content. I think this is a win, overall.

One other option is email newsletters. While they take a bit of work, letting family and friends know where you are at in life in a less intrusive way can perform some of the work that Facebook posts do.

And one last option is this blog! It’s a place on the internet where people from my past can find me. And I think I’m going to aim for weekly link roundups. I’m loosely inspired by other link blogging practices, and it will fit nicely with my use of RSS readers. By posting my thoughts, it allows for effective one-to-many conversation to a general audience.

An alternative for keeping connections

I’ve had a Facebook account for 20 years, which makes it an interesting snapshot of my life. It spans from high school to grad school to where I’m at now. I really do appreciate that in one place, I can connect to so many people. But for a lot of the people in my friends list, we don’t really communicate much directly

I think there’s two pieces to the role that Facebook plays here: The first is that Facebook becomes a means of tracking my social history. It’s an archive of who I’ve known and when (and a way of seeing where they’re at now). THe other piece is that it becomes a functional address book. I don’t have to worry about updating it, so long as my friends keep their accounts active and running.

But what’s great is that both of these things are pretty easy to solve. For people I am actively socially connected to, I can make sure that I have some stable ways of communicating with them, and have written that down somewhere. If people want to find me, I have this website. And documenting who’s been a part of my life? Well, I work making documentation and like building automations to help build and keep it up to date.

This sounds like a project!

Getting your data from Facebook

One of the first things to note is that at any point in time, you can make a backup of the data for your Facebook account. Since I have 20 years of data, this is actually kind of large and cumbersome to deal with. To get a download, there are several steps to go through, and you’ll download what is likely a sizable zip containing all your photos and lots of advertising data.

For this project I just needed a small part of the data - the information about my contacts. You can request this in HTML or JSON, but for ease of working with the data, I went with JSON. If you are looking to explore and browse through your copy of the data, the HTML download is a good option.

The data in the contacts section is pretty minimal, with the following structure:

{
    "friends_v2": [
      {
        "name": "A Person",
        "timestamp": 1726777876
      }
    ]
}

Ok, so it’s pretty sparse. The date is a unix timestamp, which will be easy enough to handle later. But at least it’s a start for what I’m trying to recapture!

Note: If you’re not into Python, you can easily build the address book part of this using spreadsheets, the HTML export, and contacts apps. Highlight all the text from the contacts page in your HTML export, then copy and paste into Excel or Google sheets. You can use a formula and the auto-complete function to bring the dates into the same row, and VLOOKUP to merge this with your contacts export.

Planning the project

Obsidian has rapidly become one of my favorite tools for organizing notes for self-directed learning, household projects, or hobbies. The thought is it would be pretty nice to use Obsidian as a way of handling information about my friends as well. So, after looking at the data, I started to think about how I’d want this information to look in Obsidian.

I don’t want a page per Facebook contact, since the goal isn’t to recreate Facebook profile pages. So I need to filter the list of Facebook contacts to people that I want to be sure to create contact details for in an address book structure. The people that are more historical contacts will go to History pages. History pages would be groups of people with any applicable contact info that I had available.

With a plan for what the output of the script (or scripts) would be, this meant that I would need to pass through the list of contacts at least once, and add the following details to each contact: whether they’d be in the address book or social history, and what kinds of categories they would fall under. For categories, I’d aim for at least three per contact — where, when, and what kind of context I added them in. So for example, someone from highschool cross-country would get “london, highschool, cross-country” as the list of tags. This should give a fairly interesting structure to the social history pages.

I also realized that I have a wealth of contact information already available to me. As an Android user, I made regular use of my phone contacts. Ultimately, I’d love to be able to sync the data associated with my Obsidian addressbook with my phone contact list as needed. This could be a stretch goal - but the primary thing would be to merge phone contacts with Facebook friends, and output the data to useful notes in my Obsidian Vault.

Carrying this out

Originally, I was hoping it would make sense to do this as a single script. At the end of the day though, a more modular approach to this made sense. With over 500 Facebook friends, categorization would be something that I would want to pick up and come back to over a period of multiple days, so a separate command line prompt that I could terminate and come back to seemed like it’d be fine for categorization.

So I settled on four separate scripts: one to merge the contacts and save that to an intermediary JSON file, a simple command line script to prompt me to categorize and tag connections, and finally, two scripts to generate output from the intermediate JSON file.

Overall, the coding was pretty simple and straightforward: the first script merge_contacts.py takes your Facebook contacts JSON export, creates a dataframe, converts the CSV export of my Android contacts to a data frame, merges them, then dumps the resulting dataframe to JSON. The matching could be improved, but it does what it needs to do. The second script, review_contacts.py goes through the JSON file, and prompts the user to categorize each contact, providing relevant information. I set it up so the user could save and exit the script at any time using ctrl-C.

What was a bit more fun was coming up with templates for each doc. Since Obsidian allows you to enter properties for each contact, I decided to write every key from the JSON file to properties of an entry in the address book. If I wanted to, I could use templating features to update the body based on the properties, but for a test MVP, I decided to keep things simple with the Obsidian templates, and created a series of markdown tables that would correspond to groupings of contact information. For social history articles - I decided I simply wanted a list of connections that fell under that category, with key contact information (email, city, etc.) following their name if available. Ideally, the core address book would be significantly smaller.

Writing the documents to files was pretty simple. Come up with two template docs in markdown, and identify which pieces of information needed to be in both, then convert the markdown templates to f-strings, writing in variables from the data as needed. From there, it was pretty quick to write two scripts that went through the JSON entries. The first script, create_address_book.py, would generate address book entries. Any contact flagged as needing to be added to the Address Book would have a unique file created in a directory. Then it would dump key/value pairs from the JSON into YAML frontmatter for the Obsidian note. This helps with updating and merging data in the future, and can be used with Data View in Obsidian to for reporting and queries. Finally, it builds a collection of tables to provide more natural viewing for the note.

For the history pages, create_soc_history.py would load the JSON, and check to see if there were any contacts that hadn’t been processed by the review script. This prompts a user warning, encouraging them to finish the review step before proceeding with this dataset. It then generates a set of all tags entered during the review, and loops through the list of labels. For each label, it prompts the user to enter a description that would be used in the note. Finally, this script generates a file using a template, and appends contact details to the file if the contact is tagged with this label.

The test run

Using the header of the Android CSV file and the structure of the Facebook JSON, I created a test dataset that would build five contacts into a single dataset, so that I could see how data would carry through from both the Facebook side and the Android side.

I was pretty pleased with how this turned out, easily generating notes that listed contacts by label, and loading connection details into the address book. Next up is to spend some time thinking of edge-cases and ways to handle them: special characters are the number one thing I’m thinking about, but also improved matching.

Tagging and categorizing my Facebook friends list will be significantly more involved run, and there are some usability things that I’m going to improve before I go too much further, but I’m pretty happy with the results.

What’s next

There’s a few things to clean up: improving incrementing and spacing in the review_contacts.py script, writing tests, and actually going through the process with my own Facebook data (I did test the merge already, and have have more than 600 contacts to review). The idea got into my head too to add LinkedIn data, but I really didn’t want to review what was likely more than 1000 connections. Maybe if I continue to push ahead on this a bit. But I do want to get back to other side projects.

At this stage, I’m happy with the resulting notes files. I’ll publish the project following a bit of the tidying work, in case your curious or want to do the same thing.

Things have been kind of crazy in the world lately — but working on this side project has felt good, like I’m bringing something back into my control, and it’s encouraging me to be more engaged with the people who matter to me.

Hopefully this inspires you to find ways to take more active control of your life too!

How I Follow Local News and Events

Sat, 25 Jan 2025 12:00:00 -0400

One of the main reasons people use social media is to stay connected to the flow of information within their community.

I’ve been intentionally disentangling my digital life from Meta over the past several years. I’ve essentially stopped actively using Facebook and only use certain communication services because they’re preferred for group chats. Finishing this process has become more urgent for me given their recent overtly anti-LGBT policies.

This shift has made finding and keeping up with local news and events more of a choose-your-own-adventure. Here’s the solution I’ve found that works for me.

The basics

For news, I need a tool that presents stories chronologically. I do not want a recommendation algorithm. I want to preview titles and selectively read articles. Ideally, I can also save stories for later or potentially re-blog them. Publication feeds like Atom and RSS are perfect for this!

Unfortunately, I stopped using RSS readers when Google Reader shut down. Facebook and Twitter became my de facto replacements, but in hindsight, this resulted in a worse internet. So, I’ve been wanting to reclaim how I interact with online content.

After considering my needs and doing some research, I landed on Inoreader. The free tier meets most of my needs, but I’m debating moving to paid. Despite some limitations (e.g., the number of feeds, inability to adjust the feed check frequency), I appreciate its rule creation, filtering, and global search capabilities. These features prevent me from becoming overwhelmed by too many unchecked feeds.

Adding a feed is easy. I locate the RSS icon (an orange square with white curved lines) on the website whenever possible. If not, I open Inoreader, click the subscribe button, and search for the website’s main URL. Inoreader is usually good at finding the feed information.

Events are trickier. My primary interest is what’s happening in my local communities. Electronic calendars are great for this, and many organizations offer iCalendar (.ics) feeds. For cross-device and multi-user compatibility, I use Google Calendar. It’s not the most innovative choice, but it works well for me given the range of devices I use.

Adding another calendar feed to Google Calendar is simple. I find the iCal feed URL (usually labeled “iCal” or “Subscribe”), copy it, and then go to my Google Calendar. Under “Other calendars,” I can add the new feed. I will color coordinate events calendars, and can filter them in and out of my calendar when I’m curious about what’s going on.

Local news

Here’s the local news I follow:

The Community Edition (Feed): An alt-weekly newspaper run by Wilfrid Laurier University Student Publications, covering local events, culture, and providing a human perspective on the Waterloo Region.
CBC News Kitchener Waterloo (Feed): CBC is Canada’s national broadcaster, a valuable part of our cultural and information ecosystem. This feed is filtered for regional news.
CTV News Kitchener (Feed): A local news channel owned by Bell Media, providing regular regional news updates.

Beyond traditional media, I follow these newsletters and new media options:

TL;WR (Feed): Alex Kinsella’s newsletter highlighting local events, music, and food. I’ve included it under news since it highlights the upcoming week, and doesn’t function as an event calendar.
Citified (Feed): Melissa Bowman’s newsletter focusing on municipal politics and civic engagement in Kitchener-Waterloo. If you want to learn about how municipal politics works in KW and what’s going on at the municipal level, this is the feed to follow.

Finally, for breaking news and local discussions, I monitor these subreddit. Using an RSS reader is less distracting than the reddit interface, and I typically mark posts as read in bulk:

Kitchener Subreddit (Feed)
Waterloo Subreddit (Feed)

These local news websites lack RSS/Atom feeds, but I’d add them to Inoreader with a paid subscription:

City News Kitchener: Rogers Media operates the City News brand, however they do not have an RSS feed.
AM570: This is local news radio, also part of Rogers Media
The Record: The Waterloo Region record is owned and operated by Torstar/Metroland. They offer email subscriptions, but their RSS feed has been defunct since June 2023.

Calendars and events

My event calendar subscriptions reflect my involvement in the tech and local queer communities:

WatCamp: This is a feed of tech sector events in the Kitchener Waterloo region.
Spectrum: The Rainbow Community Calendar from Spectrum, a queer community organization. (To get a feed, click the calendar’s menu icon, go to preferences, and select the iCalendar feed.)
Waterloo Public Library: Libraries are a wonderful community resource, and have interesting programs and special events. (Their feed service includes filters set on the calendar.)
The Princess Cinema (ICS Feed) A local indie cinema in Waterloo.

I also regularly check these calendars (even without subscription options):

Final thoughts

This framework effectively connects me with local news and events. Importantly, it’s not algorithm-driven. I see published items chronologically and choose what to engage with. This is a more proactive and empowering approach compared to the algorithmic whims of social media. It requires more effort, but the control and awareness of my information intake are worthwhile.

Addendum

While writing this, I realized others have curated similar resources! If you have other feeds to suggest, let me know, and I’ll link to them:

feeds.off-topic.kwlug.org The local Linux users group has a comprehensive list of calendars and news feeds. I will probably update my list based on this.
WR Dashboard An aggregator project that lists multiple RSS feeds.

Project Hinzelmann: Building a Household RAG App

Sun, 01 Dec 2024 12:00:00 -0400

I’ve been thinking about how generative AI impacts the ways people find, retrieve, and access information. As a technical writer, my job involves helping build systems for these purposes. This lead me to consider the ways I could build skills in this area. Inspired by Luke Hsiao’s house documentation project, I’ve been wanting to implement a document system for managing information about my house.

The thought is that bringing together these two projects, I’ll be able to create a small household-generative AI application. I’ll share my learnings and challenges along the way. And, since projects are a little more fun with cheeky names, I’m going to call this project Hinzelmann — after the figure from German folklore. Why is it cheeky? Well the Hinzelmann was a helpful figure, they were also a bit of a trickster and troublemaker.

Why use this as a case to explore generative AI?

Generative AI is a powerful UX for information retrieval. Think about how we go about finding information for a second. Let’s start with a relatively simple task: writing the regex to identify a credit card number in a text response. Regex is a great way to find patterns in strings of text, but the syntax can be difficult to parse and sometimes, for common tasks, it’s easiest to look up a pattern that already works for your case.

Let’s do a traditional websearch:

And we’ll go into stackoverflow and read a little ways down. And we have a (relatively) trustworthy answer:

It takes effort on the part of the user to assess the linked source, parse the source information, and assess how trustworthy the information is. This is fairly cognitively complex - but it’s research skills!

While using a copilot:

You are provided an authoritative answer without additional context cluttering the results.

Most users will understandably prefer this streamlined experience to the traditional search experience. It is fewer clicks, and much more focused as an experience. But there are some concerns you should have about this: LLMs are not search. They can behave like search — returning the most proabable sequence of responses to queries, but they have a key limitation. An LLM is trained on publicly available data up until a certain point in time. They don’t have current text patterns as part of the model.

LLMs are a poor search tool when you’re looking for new, specific, or private information: this is exactly the sort of information related to household projects, tasks, appliances, and tools. Ideally I’ll be able to use it to help plan projects, identify tasks that should be done, etc. Hopefully, I’ll be able to ask the application questions like “When did I last replace the air filter?”, “What’s the model number of our furnace?”, and so on.

RAG more carefully

One of the main architectures for trying to resolve this issue is what’s known as retrieval augmented generation. An LLM can adopt context: additional data that can be used to help shift the probability of it’s output.

The context window of an LLM depends on a number of factors — Claude’s projects have a 100mb limit for files that can be used as context. The thought is that in an LLM powered application to interact with documentation, you can query the documentation so that it can be used as particular context when providing an answer. This way the LLM has access to content that it wasn’t trained on.

Here’s the overall structure:

Documentation is generated and maintained in a helpful and lightweight environment.
Scripts and tools convert the documentation to a form that can be supplied to the LLM application as context.
A user interacts with the LLM through (some kind of) interface.
The inputs from the user are used to query the documentation.
The query results are passed to the LLM as context.
The output of the LLM is generated from both context and user text.

Why am I excited about this? Well, it’s a small, self-contained project about an emerging technology. I could, for example, probably skip to an effective similar result with Claude (my notes will be well within its entire context window) or existing tools for integrating note apps with ChatGPT. But this is an opportunity to explore model choice and the architecture necessary to build these kinds of applications.

I haven’t decided on what the actual build will look like yet (I’ve started research and some notes), but it’s also nice in that it puts me more in touch with the cost of running these models. For a wide range of uses, we’re obscured from seeing the costs of using these tools (both in terms of the actual expense, but also the externalities). By managing the budget and toolchain, I can be better equipped to understand the actual implications of these tools (deciding between a local LLM and an API based instance will be interesting!).

The plan

Here’s what the project looks like in terms of phases:

Phase 1 – Content Creation: Document my house, with an eye towards notes that are well suited for this use-case.
Phase 2 – Retrieval Tooling: Build scripts and tools to convert the content to a database that can be used with the generative AI tools of my choosing.
Phase 3 – Back-end Implementation: Implement an application back-end to handle key tasks for handling the query and context retrieval.
Phase 4 – Front-end Implementation: Build an interface for this so that I can interact with it without using CLI tools.

Overall the plan is to blog my way through this: I’ll create posts explaining decisions and steps that I take as I work my way through the project. How am I structuring my house documents? What decisions am I making to try and get the best result at the end? How did I decide on a model? Should I run that model locally or in the cloud?

Potential challenges

I’m excited to take this on, but it’s going to be a learning experience throughout the project. I’d consider myself ok with writing scripts and simple tools, but not a full developer by any means. In a lot of ways, this feels straight-forward: there’s nothing radically new or interesting about any part of this project, but it will be instructive to assemble these parts.

Some tool choices are going to be easy (Github, Obsidian, Python) while other parts of the project are new to me (choosing a vector database and query engine). It’s also going to require a bit of a period of dedicated work on top of regular chores — I do think the benefits will be worthwhile. Having improved notes about the house will help me with those chores and integrating them into my life, but this will take a bit more discipline on these matters.

Alternatives

This is a complicated way of doing the project, but there’s value in doing overly complicated things when you’re interested in building skills.

Here are some simple alternatives:

Claude’s Projects allows you to store a collection of files as part of individual projects. The documentation base for your house is probably going to fall within the size window.
You could probably achieve a similar result using Gemini Pro and Google Drive. Gemini Pro has a large context window, is a general purpose LLM, and can interact with your Google Drive content.

How to follow and contribute

You can subscribe to my blog feed for my site to receive updates on this project. I’ll be sharing code samples, documentation structure and more. And if you’d like to get in touch with me to discuss the project or have any advice, you can reach out to me through my contact page.

Introduction

Mon, 02 Sep 2024 15:10:46 -0400

Welcome to my blog!

My name is Kevin.

I am a software technical writer in Canada and this is a return to blogging after a few years. I previously blogged about trail running in and around my home province. Up until recently, I was happy with my personal website as a repository for my CV and a small home space on the web.

Running a blog in 2024 might seem a little passé, after all blogging’s heyday was over a decade ago. What I’d like to do in my first post is to talk about why and what you can expect if you come back to this blog (or follow this sites RSS feed).

Why a blog in 2024?

There are a couple of reasons why I’m returning to blogging in 2024.

Primarily, it’s an excuse to write. One of the powerful things about writing is how closely the act is tied to creating ideas. When I write technical documentation, I’m helping bring together intentions about what a tool does and creating a resource to build shared understanding. Writing (and doing it independently) is important because these ideas become clearer in the process. This is especially true for the kinds of projects I work on as a professional writer.

So, this blog will be a repository for the “whys” and “hows” of the things I do when I’m writing—a place for those ideas to become more concrete. It will also be a place for other people to understand how they can do similar things. I also think it’s important to advocate for the kind of work we do in software companies. In some cases, people might make assumptions about the kinds of projects and work we can take on. I hope I can showcase the value we bring to software companies.

Now, all of this could be done with a service like Medium or Substack. After all, if you just want to write, those are good ways to go. You could then have your old site link to the Medium posts.

Why a personal website?

I was already committed to owning a domain and having a website as part of maintaining a bit of personal space on the internet.

One big reason is that I’m looking to stay sharp on my skills for building and managing websites using a variety of tools, such as Github, cloud computing and static site generators. I find fiddling with these tools fun and rewarding! This site is built using Hugo, but there are many other options. This kind of technology is flexible, freely available, and has strong community support.

By authoring on my own computer, all of my content is already on my laptop. I don’t have to export my writing elsewhere. I can also write using the tools of my choosing (Git for version control, my preferred editor, Markdown, etc.), which is a definite plus.

I believe the internet is at its best when it provides opportunities for independent or collaborative efforts. Building and maintaining my own website, with its own content, is part of a project to make the internet a better place. I want the internet to be filled with diverse perspectives and stories. I want it to have meaningful writing that’s meant to communicate ideas and points of view.

I’ve modified this Hugo theme to fit with the principles of the Indieweb, because my personal outlook on technology and content aligns with the principles and goals of this movement. I want to own my identity on the web, and my content. By writing it here, I’ll have local copies of all my posts. And above all, fiddling with websites and computers is fun.

So, these are the reasons I’m returning to blogging. Thanks for coming along as a reader!

What can you expect on this blog?

Primarily, I’ll be talking about professional topics. As a software technical writer, my job is to produce useful and clear writing that explains how to do things with software products. This is an interesting field! There’s a lot to understanding how people learn and use software. And while I have produced pieces ranging from white papers to reference documents and learning modules, what I really enjoy is thinking about the design and upkeep of knowledge.

Technical writing is about being able to build resources that are useful and clear. My best experiences with documentation involved well-built tutorials, carefully crafted conceptual explanations, and clear answers to questions I was struggling to articulate. And I think this is why, even though the profession is changing with the advent of generative AI, I don’t think our role is going away.

Projects I have in mind for this website include:

Explaining how I approach certain kinds of processes, work situations, and solutions.
Discussions of emerging technologies and their impact on the profession.
Documenting projects and things that I’m working on, as I regularly use coding scripting, and various tools.
Book read-alongs and comments on media that relates to my professional life.
Posts about social trends working in technology, and thoughts from community projects I’m interested in organizing.

I won’t be holding myself to a regular publishing schedule, but I am aiming for roughly monthly posts. If you have any thoughts or ideas for posts, feel free to reach out to me through my contact page or on social media!