Simon Willison's Weblog: writing

Quoting Giles Turnbull

2026-04-08T15:18:49+00:00

I have a feeling that everyone likes using AI tools to try doing someone else’s profession. They’re much less keen when someone else uses it for their profession.

— Giles Turnbull, AI and the human voice

Tags: ai-ethics, writing, ai

My current policy on AI writing for my blog

2026-03-01T16:06:43+00:00

Because I write about LLMs (and maybe because of my em dash text replacement code) a lot of people assume that the writing on my blog is partially or fully created by those LLMs.

My current policy on this is that if text expresses opinions or has "I" pronouns attached to it then it's written by me. I don't let LLMs speak for me in this way.

I'll let an LLM update code documentation or even write a README for my project but I'll edit that to ensure it doesn't express opinions or say things like "This is designed to help make code easier to maintain" - because that's an expression of a rationale that the LLM just made up.

I use LLMs to proofread text I publish on my blog. I just shared my current prompt for that here.

Tags: blogging, writing, ai, generative-ai, llms, ai-ethics

Writing about Agentic Engineering Patterns

2026-02-23T17:43:02+00:00

I've started a new project to collect and document Agentic Engineering Patterns - coding practices and patterns to help get the best results out of this new era of coding agent development we find ourselves entering.

I'm using Agentic Engineering to refer to building software using coding agents - tools like Claude Code and OpenAI Codex, where the defining feature is that they can both generate and execute code - allowing them to test that code and iterate on it independently of turn-by-turn guidance from their human supervisor.

I think of vibe coding using its original definition of coding where you pay no attention to the code at all, which today is often associated with non-programmers using LLMs to write code.

Agentic Engineering represents the other end of the scale: professional software engineers using coding agents to improve and accelerate their work by amplifying their existing expertise.

There is so much to learn and explore about this new discipline! I've already published a lot under my ai-assisted-programming tag (345 posts and counting) but that's been relatively unstructured. My new goal is to produce something that helps answer the question "how do I get good results out of this stuff" all in one place.

I'll be developing and growing this project here on my blog as a series of chapter-shaped patterns, loosely inspired by the format popularized by Design Patterns: Elements of Reusable Object-Oriented Software back in 1994.

I published the first two chapters today:

Writing code is cheap now talks about the central challenge of agentic engineering: the cost to churn out initial working code has dropped to almost nothing, how does that impact our existing intuitions about how we work, both individually and as a team?
Red/green TDD describes how test-first development helps agents write more succinct and reliable code with minimal extra prompting.

I hope to add more chapters at a rate of 1-2 a week. I don't really know when I'll stop, there's a lot to cover!

Written by me, not by an LLM

I have a strong personal policy of not publishing AI-generated writing under my own name. That policy will hold true for Agentic Engineering Patterns as well. I'll be using LLMs for proofreading and fleshing out example code and all manner of other side-tasks, but the words you read here will be my own.

Chapters and Guides

Agentic Engineering Patterns isn't exactly a book, but it's kind of book-shaped. I'll be publishing it on my site using a new shape of content I'm calling a guide. A guide is a collection of chapters, where each chapter is effectively a blog post with a less prominent date that's designed to be updated over time, not frozen at the point of first publication.

Guides and chapters are my answer to the challenge of publishing "evergreen" content on a blog. I've been trying to find a way to do this for a while now. This feels like a format that might stick.

If you're interested in the implementation you can find the code in the Guide, Chapter and ChapterChange models and the associated Django views, almost all of which was written by Claude Opus 4.6 running in Claude Code for web accessed via my iPhone.

Tags: blogging, design-patterns, projects, writing, ai, generative-ai, llms, ai-assisted-programming, vibe-coding, coding-agents, agentic-engineering, site-upgrades

3 shell scripts to improve your writing, or "My Ph.D. advisor rewrote himself in bash."

2024-12-14T18:20:50+00:00

3 shell scripts to improve your writing, or "My Ph.D. advisor rewrote himself in bash."

Matt Might in 2010:

The hardest part of advising Ph.D. students is teaching them how to write.

Fortunately, I've seen patterns emerge over the past couple years.

So, I've decided to replace myself with a shell script.

In particular, I've created shell scripts for catching three problems:

abuse of the passive voice,

weasel words, and

lexical illusions.

"Lexical illusions" here refers to the thing where you accidentally repeat a word word twice without realizing, which is particularly hard to spot if the repetition spans a line break.

Matt shares Bash scripts that he added to a LaTeX build system to identify these problems.

I pasted his entire article into Claude and asked it to build me an HTML+JavaScript artifact implementing the rules from those scripts. After a couple more iterations (I pasted in some feedback comments from Hacker News) I now have an actually quite useful little web tool:

tools.simonwillison.net/writing-style

Here's the source code and commit history.

Via lobste.rs

Tags: bash, tools, writing, ai, generative-ai, llms, ai-assisted-programming, claude-artifacts, prompt-to-app

Quoting Steve Klabnik

2024-11-13T03:35:23+00:00

This tutorial exists because of a particular quirk of mine: I love to write tutorials about things as I learn them. This is the backstory of TRPL, of which an ancient draft was "Rust for Rubyists." You only get to look at a problem as a beginner once, and so I think writing this stuff down is interesting. It also helps me clarify what I'm learning to myself.

— Steve Klabnik, Steve's Jujutsu Tutorial

Tags: version-control, writing, steve-klabnik

Quoting Cal Newport

2024-10-03T19:43:23+00:00

At first, I struggled to understand why anyone would want to write this way. My dialogue with ChatGPT was frustratingly meandering, as though I were excavating an essay instead of crafting one. But, when I thought about the psychological experience of writing, I began to see the value of the tool. ChatGPT was not generating professional prose all at once, but it was providing starting points: interesting research ideas to explore; mediocre paragraphs that might, with sufficient editing, become usable. For all its inefficiencies, this indirect approach did feel easier than staring at a blank page; “talking” to the chatbot about the article was more fun than toiling in quiet isolation. In the long run, I wasn’t saving time: I still needed to look up facts and write sentences in my own voice. But my exchanges seemed to reduce the maximum mental effort demanded of me.

— Cal Newport

Tags: writing, generative-ai, chatgpt, ai, llms

Give people something to link to so they can talk about your features and ideas

2024-07-13T16:06:28+00:00

If you have a project, an idea, a product feature, or anything else that you want other people to understand and have conversations about... give them something to link to!

Two illustrative examples are ChatGPT Code Interpreter and Boring Technology.

ChatGPT Code Interpreter is effectively invisible

ChatGPT Code Interpreter has been one of my favourite AI tools for over a year. It's the feature of ChatGPT which allows the bot to write and then execute Python code as part of responding to your prompts. It's incredibly powerful... and almost invisible! If you don't know how to use prompts to activate the feature you may not realize it exists.

OpenAI don't even have a help page for it (and it very desperately needs documentation) - if you search their site you'll find confusing technical docs about an API feature and misleading outdated forum threads.

I evangelize this tool a lot, but OpenAI really aren't helping me do that. I end up linking people to my code-interpreter tag page because it's more useful than anything on OpenAI's own site.

Compare this with Claude's similar Artifacts feature which at least has an easily discovered help page - though the Artifacts announcement post was shared with Claude 3.5 Sonnet so isn't obviously linkable. Even that help page isn't quite what I'm after. Features deserve dedicated pages!

GitHub understand this: here are their feature landing pages for Codespaces and Copilot (I could even guess the URL for Copilot's page based on the Codespaces one).

Update: It turns out there IS documentation about Code Interpreter mode... but I failed to find it because it didn't use those terms anywhere on the page! The title is Data analysis with ChatGPT.

This amuses me greatly because OpenAI have been oscillating on the name for this feature almost since they launched - Code Interpreter, then Advanced Data Analysis, now Data analysis with ChatGPT. I made fun of this last year.

Boring Technology: an idea with a website

Dan McKinley coined the term Boring Technology in an essay in 2015. The key idea is that any development team has a limited capacity to solve new problems which should be reserved for the things that make their product unique. For everything else they should pick the most boring and well-understood technologies available to them - stuff where any bugs or limitations have been understood and discussed online for years.

(I'm very proud that Django has earned the honorific of "boring technology" in this context!)

Dan turned that essay into a talk, and then he turned that talk into a website with a brilliant domain name:

boringtechnology.club

The idea has stuck. I've had many productive conversations about it, and more importantly if someone hasn't heard the term before I can drop in that one link and they'll be up to speed a few minutes later.

I've tried to do this myself for some of my own ideas: baked data, git scraping and prompt injection all have pages that I frequently link people to. I never went as far as committing to a domain though and I think maybe that was a mistake - having a clear message that "this is the key page to link to" is a very powerful thing.

This is about both SEO and conversations

One obvious goal here is SEO: if someone searches for your product feature you want them to land on your own site, not surrender valuable attention to someone else who's squatting on the search term.

I personally value the conversation side of it even more. Hyperlinks are the best thing about the web - if I want to talk about something I'd much rather drop in a link to the definitive explanation rather than waste a paragraph (as I did earlier with Code Interpreter) explaining what the thing is for the upmteenth time!

If you have an idea, project or feature that you want people to understand and discuss, build it the web page it deserves. Give people something to link to!

Tags: github, marketing, seo, writing, openai, chatgpt, claude, boring-technology, code-interpreter, coding-agents

Quoting Andrew Ti

2024-06-23T05:22:27+00:00

The people who are most confident AI can replace writers are the ones who think writing is typing.

— Andrew Ti

Tags: writing, ai, generative-ai, copywriting

Wikipedia Manual of Style: Linking

2024-06-22T14:15:54+00:00

Wikipedia Manual of Style: Linking

I started a conversation on Mastodon about the grammar of linking: how to decide where in a phrase an inline link should be placed.

Lots of great (and varied) replies there. The most comprehensive style guide I've seen so far is this one from Wikipedia, via Tom Morris.

Via Tom Morris

Tags: links, wikipedia, writing

Quoting Michal Zalewski

2024-06-04T21:13:29+00:00

You don’t need to be the world’s leading expert to write about a particular topic. Experts are often busy and struggle to explain concepts in an accessible way. You should be honest with yourself and with your readers about what you know and don’t know — but otherwise, it’s OK to write about what excites you, and to do it as you learn.

— Michal Zalewski

Tags: writing, blogger

Quoting Alex Jason

2024-04-25T14:17:57+00:00

The only difference between screwing around and science is writing it down

— Alex Jason, via Adam Savage

Tags: writing, science

Write about what you learn. It pushes you to understand topics better.

2023-08-14T14:50:48+00:00

Write about what you learn. It pushes you to understand topics better.

Addy Osmani clearly articulates why writing frequently is such a powerful tool for learning more effectively. This post doesn’t mention TILs but it perfectly encapsulates the value I get from publishing them.

Via Hacker News

Tags: blogging, writing, til, addy-osmani

Quoting u/Ashamed_Apricot6626

2023-04-11T18:20:36+00:00

I literally lost my biggest and best client to ChatGPT today. This client is my main source of income, he’s a marketer who outsources the majority of his copy and content writing to me. Today he emailed saying that although he knows AI’s work isn’t nearly as good as mine, he can’t ignore the profit margin. [...] Please do not think you are immune to this unless you are the top 1% of writers. I just signed up for Doordash as a driver. I really wish I was kidding.

— u/Ashamed_Apricot6626

Tags: writing, ethics, chatgpt, ai, llms, ai-ethics, copywriting

Quoting Ryan Bradley

2023-02-27T18:10:10+00:00

I think now of all the kids coming up who are learning to write alongside ChatGPT, just as I learned to write with spell-check. ChatGPT isn’t writing for them; it’s producing copy. For plenty of people, having a robot help them produce serviceable copy will be exactly enough to allow them to get by in the world. But for some, it will lower a barrier. It will be the beginning of their writing career, because they will learn that even though plenty of writing begins with shitty, soulless copy, the rest of writing happens in edits, in reworking the draft, in all the stuff beyond the initial slog of just getting words down onto a page.

— Ryan Bradley

Tags: chatgpt, writing, ai, generative-ai, llms

What to blog about

2022-11-06T17:05:37+00:00

You should start a blog. Having your own little corner of the internet is good for the soul!

But what should you write about?

It's easy to get hung up on this. I've definitely felt the self-imposed pressure to only write something if it's new, and unique, and feels like it's never been said before. This is a mental trap that does nothing but hold you back.

Here are two types of content that I guarantee you can produce and feel great about producing: TILs, and writing descriptions of your projects.

Today I Learned

A TIL - Today I Learned - is the most liberating form of content I know of.

Did you just learn how to do something? Write about that.

Call it a TIL - that way you're not promising anyone a revelation or an in-depth tutorial. You're saying "I just figured this out: here are my notes, you may find them useful too".

I also like the humility of this kind of content. Part of the reason I publish them is to emphasize that even with 25 years of professional experience you should still celebrate learning even the most basic of things.

I learned the "interact" command in pdb the other day! Here's my TIL.

I started publishing TILs in April 2020. I'm up to 346 now, and most of them took less than 10 minutes to write. It's such a great format for quick and satisfying online writing.

My collection lives at https://til.simonwillison.net - which publishes content from my simonw/til GitHub repository.

Write about your projects

If you do a project, you should write about it.

I recommend adding "write about it" to your definition of "done" for anything that you build or create.

Like with TILs, this takes away the pressure to be unique. It doesn't matter if your project overlaps with thousands of others: the experience of building it is unique to you. You deserve to have a few paragraphs and a screenshot out there explaining (and quietly celebrating) what you made.

The screenshot is particularly important. Will your project still exist and work in a decade? I hope so, but we all know how quickly things succumb to bit-rot.

Even better than a screenshot: an animated GIF screenshot! I capture these with LICEcap. And a video is even better than that, but those take a lot more effort to produce.

It's incredibly tempting to skip the step where you write about a project. But any time you do that you're leaving a huge amount of uncaptured value from that project on the table.

These days I make myself do it: I tell myself that writing about something is the cost I have to pay for building it. And I always end up feeling that the effort was more than worthwhile.

Check out my projects tag for examples of this kind of content.

So that's my advice for blogging: write about things you've learned, and write about things you've built!

Update 22nd December 2024: I identified a third useful category: writing about things you've found.

Tags: blogging, writing

Writing better release notes

2022-01-31T20:13:50+00:00

Release notes are an important part of the open source process. I've been thinking about these a lot recently, and I've assembled some thoughts on how to do a better job with them.

Write release notes. Seriously - if you want people to take advantage of the work you have been doing to improve your projects, you need to tell them about it!
Include the date. The date matters a lot, because I want to be able to determine how old a release is - especially important for the dependencies I am using.

It’s much more reasonable to assume people will be running as a minimum a version from 3 years ago than one that came out last week.
Make sure people can link to the release notes for a version. This can be a page-per-release or an anchor target on the releases page, but it needs to be possible and it needs to be discoverable.

There are some projects for which I have to view source on the HTML page to find the anchor links for the version headers - don’t make me do that!
For larger releases, break them up with headers. “New features” v.s. “Bug fixes” is a useful distinction.
Emphasize the highlights. It can be easy for the highlights of a larger release to get lost in a sea of bullet points. I’ll sometimes include an introductory paragraph highlighting the major themes.
Link to relevant documentation from the release notes. If I want to know more about a new feature that should be the best place for me to start.
Flesh them out with examples and screenshots. Most release notes are pretty dry - there’s no space limit on these things, so feel free to use all of the tools at your disposal to best answer the question “what has changed and why does this matter to me?”
Link to the associated issue thread. If I want to know more about a feature, and you’ve been using issues effectively, the issue link can tell me the entire story of the new feature in more detail than anything else.
Credit your contributors! If someone helped build a feature the release notes are a great place to give them a shout out.
Once shipped, let people know. I mainly use Twitter for this, but I also write about releases on my blog (in my weeknotes) and push out news about major releases through my project newsletter.

When I tweet my release notes (recent example) I include both a link to them and, if they’re short, a screenshot of the release notes with an alt= attribute duplicating their content.

GitHub Releases and GitHub Actions

I really like the GitHub releases feature. You can easily create new release attached to tags, and each release gets its own linkable page. Release notes are written in Markdown and you can edit them later on, expanding them further and fixing any typos or errors.

Releases pages also automatically link to a zip or .tar.gz file of your repository at that tag, and you can attach binary builds to that page too.

Plus they have a good API, and they integrate well with GitHub Actions.

I manage all of my Python package releases using this - I have an actions workflow which triggers on a new GitHub release, builds and packages that tag and then uploads it to PyPI - so all I have to do is click “new release” and fill in the form and my automation does the rest of the work.

I use the GitHub API to show links to my most recent releases on both the Datasette homepage and my personal GitHub profile.

Annotated release notes

Something I’ve been trying with my own projects is publishing annotated release notes to accompany the official ones.

The idea here is that while the official release notes succinctly document “what changed”, the annotated ones are a place where I can provide personal notes about the new features - the background on them, what I learned along the way and my own opinions on what they are useful for and why.

I enjoy writing these, but I’ve not yet got a great feel for if people find them useful or not - so I’m not ready to recommend them as a thing that other projects should aim to replicate. I like them though, so if you write them for your project I will look forward to reading them!

Some examples

I'm a huge fan of Django's release notes - they're some of the best I've ever seen. It's worth exploring both minor releases and major releases for an example of what this looks like when it's done really well.

For my own projects, I put the most effort into the release notes for Datasette and for sqlite-utils. Both of those projects have a dedicated page in their documentation.

sqlite-utils 3.10 and Datasette 0.44 are some of my better examples.

I also write about them on my blog. Here's the full series of annotated release notes for Datasette, and my write-ups of new features added to sqlite-utils.

My smaller projects use GitHub Releases rather than having a dedicated page in their documentation. datasette-graphql 0.10 and s3-credentials 0.9 are two good examples there.

Tags: open-source, releasenotes, writing

Quoting Stephanie Morillo

2020-12-28T15:58:31+00:00

While copywriting is used to persuade a user to take a certain action, technical writing exists to support the user and remove barriers to getting something done. Good technical writing is hard because writers must get straight to the point without losing or confusing readers.

— Stephanie Morillo

Tags: writing, copywriting

Story Structure 104: The Juicy Details

2019-04-25T13:17:51+00:00

Story Structure 104: The Juicy Details

Dan Harmon (Community, Rick and Morty) wrote a fascinating series of essays on story structure for his Channel 101 film festival project. It’s worth reading the whole series, but this chapter is where things get really detailed.

Tags: writing, screen-writing

Quoting John Gruber

2018-01-25T13:43:42+00:00

I spent more time on my iPhone X review than anything I’ve written in years, and it went to paper twice. (Here’s a scan of my second printed draft, with handwritten revisions.) My thing is that I don’t use my favorite pen — which, of course, has black ink — but instead a pen with red ink. Editing is an angry, bloody act and therefore must be done in red.

— John Gruber

Tags: john-gruber, writing

Medicaid Eligibility | plainlanguage.gov

2017-11-20T01:59:44+00:00

Medicaid Eligibility | plainlanguage.gov

Useful resource for helping government writers use clear language. I love that this is an official US government website written using Jekyll and developed entirely in the open on GutHub—the commit history is fascinating.

Via Jonathan Shariat

Tags: writing

Hemingway Editor

2017-11-01T20:38:15+00:00

Hemingway Editor

Hemingway is a web-based editor that applies style checks to your writing. It looks for complicated words, unnecessary adverbs and sentences that are hard to read. It highlighted the previous sentence as hard to read. It gave this whole paragraph a Grade 8 readability score.

Tags: writing

The magic of sub-editors

2010-02-16T10:44:40+00:00

The magic of sub-editors

A neat illustration of how sub-editors work their magic, using the original article with strikes through the parts that were edited out.

Tags: john-graham-cumming, science, subeditors, writing

What is it like to write a technical book?

2008-06-20T08:18:53+00:00

What is it like to write a technical book?

Plenty of food for thought from the lead author of the new edition of High Performance MySQL. It’s amazing how Word is still an integral part of most technical book projects despite its obvious inadequacies compared to a toolchain based on plain text files and Subversion (the Django Book used ReST and Subversion to great effect).

Tags: baron-schwartz, django, plaintext, rest, subversion, word, writing

The Art & Science of JavaScript

2008-01-12T19:05:27+00:00

The Art & Science of JavaScript

The JavaScript book I contributed to is now shipping! My chapter describes how to build a Flickr / Google Maps mashup entirely using client-side code (via JSON-P).

Tags: books, flickr, google-maps, javascript, json, jsonp, sitepoint, theartandscienceofjavascript, writing

Chapter 7: Form Processing

2007-12-16T21:44:44+00:00

Chapter 7: Form Processing

The chapter on newforms I contributed to “The Definitive Guide to Django” is now online, along with the rest of the published book.

Tags: django, django-book, newforms, python, writing

Quoting John C. Welch

2007-07-12T18:23:30+00:00

Could someone please send, to whomever the hell teaches communication skills/techniques at Microsoft, a copy of the Chicago Manual, and perhaps a sixth - grade grammar text? I swear, there's almost no one from that company who can write a proper English sentence.

— John C. Welch

Tags: microsoft, john-c-welch, writing, english

Mobile Device Connectivity to Exchange using IMAP vs Exchange ActiveSync

2007-07-12T17:17:08+00:00

Mobile Device Connectivity to Exchange using IMAP vs Exchange ActiveSync

I count 14 instances of “experience” in this 1,000 word blog entry. Do real people talk like this?

Via John Gruber

Tags: activesync, communication, exchange, experience, imap, john-gruber, microsoft, weaselwords, writing

Quoting Dave Thomas

2007-03-24T15:05:51+00:00

When I write a new book [...] I plan to throw away something like the first 30 or so pages. And, because I know I'm going to do it, it doesn't worry me. I no longer have writer's block.

— Dave Thomas

Tags: dave-thomas, writing

Dave Thomas on Writing a Book

2007-03-24T14:53:31+00:00

Dave Thomas on Writing a Book

A series of articles on writing a technical book, from Pragmatic Programmer Dave Thomas.

Tags: dave-thomas, writing