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:
- 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.
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
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.
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.
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.
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.
The only difference between screwing around and science is writing it down
— Alex Jason, via Adam Savage
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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).
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.
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.
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?
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 on Writing a Book. A series of articles on writing a technical book, from Pragmatic Programmer Dave Thomas.