My checklist for publishing a blog post

post by Steven Byrnes (steve2152) · 2023-08-15T15:04:56.219Z · LW · GW · 6 comments

Contents

  Introduction
  The actual checklist! (2023-08-15 2024-01-30 version)
    Copyediting items
    Consider sharing the draft with people
    Repeat the copyediting list from above one more time if there have been massive changes
    After publishing
    Appendix: List of things that I regularly forget to treat as jargon
    Appendix: GPT-4 Copyediting prompts
None
6 comments

Introduction

Checklists are good [LW · GW]. I don’t use checklists much for my job though. (My to-do list is stylistically a kanban, not a checklist—details here [LW(p) · GW(p)] & here [LW(p) · GW(p)].)

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 [LW(p) · GW(p)] (edit: a commenter found a better / updated link to Gwern’s checklist here), and Justis’s writing advice list [LW · GW] 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)
• Check for vague “this” [LW · GW]
• Check for over-hedging [LW · GW]
• 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 [LW · GW]

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”

6 comments

Comments sorted by top scores.