My checklist for publishing a blog post
Introduction
Checklists are good. I don’t use checklists much for my job though. (My to-do list is stylistically a kanban, not a checklist—details here & here.)
But I have one exception: My checklist for publishing blog posts (an activity that I’ve been doing with some regularity—you’re reading my 114th blog post just on this forum!)
I am sharing that checklist here, not because it’s particularly good, nor because I’m recommending that other people use it (obviously it’s tailored to my idiosyncratic needs), but because I’m interested in sharing ideas and getting feedback!
Related things on this forum include a 2012 essay-publishing checklist by gwern (edit: a commenter found a better / updated link to Gwern’s checklist here), and Justis’s writing advice list which is not directly a checklist but could be made into one (and indeed I copied a few items from it). Please comment with other references and suggestions! How would your own checklist differ from mine?
A couple more bits of commentary before we begin:
Checklist workflow: Good news is that pretty much every productivity-related app (e.g. logseq, roam, obsidian, emacs-org-mode, trello, etc.) has a very nice workflow for checklists—where you make a reusable checklist template, and then insert a fresh (non-checked-off) copy into the appropriate context, and then check off the items one-by-one. If you don’t know the details, google it.
“Consider doing X” items: You’ll notice that many of these checklist items are of the form “Consider doing X”. Often what that means for me in practice is:
I get to the checklist item “Consider doing X”;
I consider doing X, and decide not to;
I happily check it off.
That’s fine! It’s not always a good use of time to make a blog post higher-quality. The one you’re reading right now is a great example: I am writing this post very quickly, and I stand by that decision.
OK, that’s enough commentary! The rest of the post is the checklist itself.
The actual checklist! (2023-08-15 2024-01-30 version)
Copyediting items
Check for unexplained or unnecessary jargon & acronyms.
Check for jargon & acronyms that are defined in one part of the post and then used in a distant part of the post without repeating the definition.
Check for unnecessarily obscure words and cultural references (for non-native English speakers)
Consider checking that all the hyperlinks actually go to the intended destination
Consider adding more hyperlinks, references, and footnotes
Consider adding a self-contained summary / table-of-contents / tl;dr to the top
Consider adding humorous things
Consider looking at each section and asking: “Can I delete this?”
Consider looking at each paragraph and asking: “Can I delete this?”
Consider whether there’s anything I can move out of the main text and into a footnote (or hyperlink)
Consider replacing (or at least supplementing) strawman arguments with better versions (even in the context of a “common misperceptions” discussion)
Consider replacing criticism with “let’s try to do better” type language
Consider replacing criticism of individuals / groups with criticism of papers / ideas / plans
Consider adding pictures, possibly including AI-generated.
Consider adding concrete examples
Brainstorm alternate titles (thanks Linch in the comments section)
Check that the title by itself (out of context) is unobjectionable (thanks Linch in the comments section)
Consider “not being lazy / rushed” (e.g. if the text says “I don’t know X” or “I didn’t check Y” etc., consider whether I should sort that out before publishing)
Make sure images / tables / etc. look OK in both light mode and dark mode (e.g. diagrams probably need a white background, not transparent).
Check that the lesswrong sidebar outline looks right
(When copy-pasting from a google doc) Check that “> blah” sections have been reformatted as proper quote blocks
(When copy-pasting from a google doc) Check that footnotes and image captions are all there
(When copy-pasting from a google doc) Check that I converted all the formulas to LaTeX
Update the preview image & preview text (at the bottom of the lesswrong pot-editing screen)
Add lesswrong categories
Make sure I acknowledged people who helped, as appropriate
Consider asking GPT for copyediting advice (see below)
Consider sharing the draft with people
(Useful text snippet: “If you DO want to read it, but DON’T expect to get around to it in the next week or two, please let me know so I can hold off publication.”)
Consider sharing draft with friends / colleagues such as [redacted]
Consider sharing draft on slacks / discords / etc. such as [redacted]
Consider sharing draft with anyone whose paper I’m citing
Consider sharing draft with anyone who I mention by name
Consider sharing draft with anyone deeply involved in a field that I’m talking about
Consider professional copyediting
Repeat the copyediting list from above one more time if there have been massive changes
After publishing
Share on Twitter, Mastodon, Threads, Bsky
Add to my website index of blog posts
Consider sharing on slacks / discords / etc. such as [redacted]
Appendix: List of things that I regularly forget to treat as jargon
“Attend to” (neuro jargon—replace with “Pay attention to”)
“Dopamine neuron” (neuro jargon—replace with “Dopamine-producing neuron”)
“AGI” (controversial/ambiguous—need to define it or avoid it)
“Distillation” (replace with “explanation”, “pedagogy”, etc.)
[etc.]
Appendix: GPT-4 Copyediting prompts
Note: These are sometimes slightly useful, but not very useful, such that I often don’t even bother. I have spent very little time exploring alternative prompts, and I am desperately hoping for better suggestions from people who have—please leave comments!
FIRST STEP: “[The following is a blog post draft. Please create a bullet point list with any typos or grammar errors.]” Then copy-paste the entire blog post text right here
“Was there any unexplained jargon in that essay?”
“Was any aspect of that essay confusing?”
“Are there particular parts of this essay that would be difficult for non-native English speakers to follow?”
“Please create a bullet-point list of obscure words that I use in the essay, which a non-native English speaker might have difficulty understanding.”
(If it’s an FAQ:) “What other FAQ questions might I add?”
“What else should I add to this essay?”
(If there’s a summary/tldr at the top:) “Is the summary at the top adequate?”
(If it pauses in the middle of something) “continue”
Re: your GPT-4 copyediting prompts: in the Playground, OpenAI nowadays lets you separate the system prompt from the actual prompt. So you might have more success if you put the role and tasks or questions for your AI “editor” into the system prompt and just paste the main text of the blogpost each time as a “user message”.
Also, once you’ve found a setup you’re happy with, you can save it in Playground (buttons in the top right) as a “preset”. And once you open a preset, it has a unique link you can open directly via a browser bookmark, or you can even make the preset publically shareable via the link. Example shared preset (without interesting settings or prompts) to demonstrate the Share functionality.
Note that if you edit a preset, you have to click on “Save” again and then select Update, otherwise your changes won’t be saved.
I suspect people should spend nonzero effort on the title, quite possibly a lot (like for a blogpost that takes 5 hours to write, somewhere between 3 minutes and 30 for an appropriate title).
I think this is very unintuitive to people, myself included. From the perspective of a writer, a title is just one line to write (and often one of the least interesting lines, as it’s unlikely that you as a writer discover something novel in the process of creating a title). But from the perspective of a (potential) reader, titles are quite important, as:
It is probably one of the most critical pieces of information for readers to decide whether something is worth investing the time to read and engage with, particularly if linked elsewhere.
It helps set the tone for how readers should engage with the rest of your essay.
Positive example: Some unfun lessons I learned as a junior grantmaker
Short, to the point, and contextually useful (someone reading this title knows both where I’m coming from, as well as have some bounds on the limitations)
Negative example: Why short-range forecasting can be useful for longtermism (old title)
The old title was bad because it led readers to believe (falsely) that the post would give an argument for the statement in the title, rather than just assume that the title is a placeholder.
It also predictably led to people being confused about the intended purpose of the post, which is more “this thing would be cool, would love to find collaborators.”
imo the newer title Early-warning Forecasting Center: What it is, and why it’d be cool is comparatively much better, though still not ideal.
For low-information readers, a title helps them decide whether/how much to be angry at you.
This can either be desirable or undesirable, depending on your intended purpose.
As I personally don’t like it when randos are angry at me, I try to screen all my titles for a “will this title seriously offend low-information people who just randomly see this title on Twitter/Facebook/Hacker News?” check.
All else equal, your title is the substring of your text that is most likely to be taken out of context, so some prudence is warranted.
Related: Crossposting my reddit comment from this comment thread on r/rational (re: the question of how some particular web fiction author achieved rapid outsized success):
The perspective that a title has vastly outsized importance also helps explain other weird things, e.g. that newspaper writers often don’t write their own headlines.
Or, put differently in the parent comment, one can picture outsized success on social media with a swiss cheese model:
Similarly, a bunch of things have to line up for an article to go viral: someone has to click on your content (A), then like it (B), and then finally follow a call to action like sharing it or donating (C). From this perspective, it’s important to put a significant fraction of one’s efforts on quality (B) into efforts on presentation / clickability (A).
(Side note: If this sounds like advocacy for clickbait, I think it isn’t. The de facto problem with a clickbaity title like “9 Easy Tips to Win At Life” is not the title per se, but that the corresponding content never delivers.)
Finally, re this part:
Another somewhat related point here is managing expectations. My experience here is from Steam games, where the best-rated video games (i.e. those with a fraction of 98-99% of positive reviews) aren’t necessarily the “best” games (whatever that would mean), but rather very good games which make it crystal clear what they are or are not. (Via trailers, screenshots, descriptions, game demos, …) As a result, people who might otherwise buy the game, not enjoy themselves, and then leave a negative review, can instead discover in advance that the game is not for them. This selection effect increases the rate of positive reviews, and leaves everyone better off.
Thanks, this is helpful.
The updated version of Gwern’s writing checklist is this one, which seems somewhat more comprehensive than in his 2012 comment, although that might be partly due to site-specific reasons?
Thanks for this! I’ve been unsatisfied with my long form writing for some time and was going to make a pre-publication checklist for future posts, and customizing this for my personal use helps me save time on that.