Simon Willison’s Weblog

Subscribe
Atom feed for writing

26 items tagged “writing”

2024

3 shell scripts to improve your writing, or “My Ph.D. advisor rewrote himself in bash.” (via) 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:

  1. abuse of the passive voice,
  2. weasel words, and
  3. 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

Screnshot of the Writing Style Analyzer tool. I have pasted in the post you are reading now, it found a weasel word "quite" in: "actually quite useful little web tool" and duplicate word "word" in: "word word twice without realizing, which is"

Here's the source code and commit history.

# 14th December 2024, 6:20 pm / writing, claude-artifacts, ai-assisted-programming, bash, generative-ai, ai, llms, tools

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

# 13th November 2024, 3:35 am / version-control, writing

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

# 3rd October 2024, 7:43 pm / writing, generative-ai, chatgpt, ai, llms

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

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!

[... 685 words]

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

Andrew Ti

# 23rd June 2024, 5:22 am / writing, ai, generative-ai

Wikipedia Manual of Style: Linking (via) 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.

# 22nd June 2024, 2:15 pm / wikipedia, links, writing

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

# 4th June 2024, 9:13 pm / writing, blogger

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

Alex Jason, via Adam Savage

# 25th April 2024, 2:17 pm / writing, science

2023

Write about what you learn. It pushes you to understand topics better. (via) 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.

# 14th August 2023, 2:50 pm / writing, til, blogging

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

# 11th April 2023, 6:20 pm / writing, ethics, chatgpt, ai, llms

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

# 27th February 2023, 6:10 pm / chatgpt, writing, ai, generative-ai, llms

2022

What to blog about

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

[... 502 words]

Writing better release notes

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.

[... 918 words]

2020

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

# 28th December 2020, 3:58 pm / writing

2019

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.

# 25th April 2019, 1:17 pm / screenwriting, writing

2018

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

# 25th January 2018, 1:43 pm / john-gruber, writing

2017

Medicaid Eligibility | plainlanguage.gov (via) 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.

# 20th November 2017, 1:59 am / writing

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.

# 1st November 2017, 8:38 pm / writing

2010

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.

# 16th February 2010, 10:44 am / subeditors, john-graham-cumming, science, writing

2008

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).

# 20th June 2008, 8:18 am / writing, word, subversion, django, rest, plaintext, baron-schwartz

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).

# 12th January 2008, 7:05 pm / javascript, writing, books, flickr, google-maps, jsonp, json, sitepoint, theartandscienceofjavascript

2007

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.

# 16th December 2007, 9:44 pm / newforms, django, django-book, writing, python

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

# 12th July 2007, 6:23 pm / microsoft, john-c-welch, writing, english

Mobile Device Connectivity to Exchange using IMAP vs Exchange ActiveSync (via) I count 14 instances of “experience” in this 1,000 word blog entry. Do real people talk like this?

# 12th July 2007, 5:17 pm / experience, weaselwords, communication, writing, microsoft, john-gruber, exchange, imap, activesync

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

# 24th March 2007, 3:05 pm / dave-thomas, writing

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

# 24th March 2007, 2:53 pm / dave-thomas, writing