My checklist for publishing a blog post

Steven Byrnes15 Aug 2023 15:04 UTC
90 points
6 comments4 min readLW link

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

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 2026-02-12 version)

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

Script for LLM copyediting

(Most of the suggestions will probably be bad! Ignore those! Take pride in ignoring them! But I bet you’ll get enough valid criticisms to make it worth the time.)

  • Hello. Can you read this attachment? If yes, let’s start with copyediting problems: typos, confusing wording, unexplained acronyms, and so on.

    • [Note: If the LLM finds more than a couple legitimate problems, I usually edit it and then start a new chat and re-ask this question, repeating until it’s all false positives.]

  • Thank you. Next: Do you have any suggestions for things (sentences, paragraphs, sections) that could be deleted, to make the piece shorter without harming the flow?

  • Can you think of any new examples, analogies, etc., that I could add?

  • Anything else that I might add to this blog post?

  • Do I make any points that seem possibly incorrect?

  • Is there any other prior art /​ literature ideas that I should be discussing?

  • Are there areas where I sound overly confident?

  • Are there areas where I’ll irritate people who disagree with me?

  • (If it’s an FAQ:) “What other FAQ questions might I add?”

  • (If there’s a summary/​tldr at the top:) “Is the summary at the top adequate?”

Normal (non-LLM) 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.

  • Consider putting “target audience” or similar near the top.

  • Check for unnecessarily obscure words and cultural references (for non-native English speakers)

  • Check for vague “this”

  • Check for over-hedging

  • 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 collapsed-by-default boxes

  • Consider adding funny things, especially near the top

    • …As a special case, if there are any concrete examples, consider making them funny

  • Make sure that the lede (first few paragraphs) has some draw—something “aha”, intriguing, funny, controversial, etc.

  • 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

    • Check that footnotes and image captions are all there

    • Check that I converted all the formulas, subscripts, and superscripts to LaTeX

    • Check that the bullets and numbered lists copied correctly

  • Items at the bottom of the lesswrong post-editing page:

    • Edit the preview image

    • Edit the preview text

    • Add lesswrong categories

    • Decide whether or not to click the checkboxes for crossposting to EA forum and/​or alignment forum (if applicable)

  • Add in an acknowledgements section (if applicable)

After publishing

  • Share on Twitter, bluesky, substack, maybe sometimes linkedin

  • Add to my website index of blog posts

  • Consider sharing on slacks /​ discords /​ etc. such as [redacted]

  • If I had made a google doc draft, put a link at the top of it to the published version

  • If I had made earlier public reference to “an upcoming post”, “next post”, etc., then go back and add in the actual link.

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

Steven Byrnes15 Aug 2023 15:04 UTC
90 points
6 comments4 min readLW link