Post Guidelines
Editing takes me a long time. Having a checklist and guidelines makes me faster. I like to collect folks’ personal writing guidelines, style guides, and their reasons to write. I found them helpful when writing my own. Some of these may be helpful for yours, too.
Some of these guidelines, I took from other folks. Some come from deep convictions. If I don’t follow those, you could take that as a sign that I’m being forced to write under duress or have been replaced by an impostor. Others, I view only as suggestions and gentle reminders.
§ Mechanics
- Read each sentence.
- Is the tense consistent?
- When drafting, I use hyphens to signify various dashes. Are all the hyphens (-), en dashes (–), and em dashes (—) correct?
- Check that phrasal adjectives are hyphenated.
- Check that I’m consistent with abbreviations and initialisms. Does it make sense to use the expanded version the first time it’s used?
- Do I use too many ellipses?
- Do I use too many parentheses?
§ Structure
- Is every piece necessary?
- Is it a short article? It shouldn’t have an Introduction section.
- Are the sections and paragraphs in the best order?
- If the headings are sentences, are they in sentence case?
- Is this part of a project?
- Does it need sidenotes?
- Does it need a code snippet?
- Does it need an up button?
- How does this relate to other things I’ve posted? How should they be connected?
§ Opening and Closing
- Review the opening sentence and opening paragraph.
[…] your lead must capture the reader immediately and force him to keep reading. It must cajole him with freshness, or novelty, or paradox, or humor, or surprise, or with an unusual idea, or an interesting fact, or a question. Anything will do, as long as it nudges his curiosity and tugs at his sleeve.
Next the lead must do some real work. It must provide hard details that tell the reader why the piece was written and why he ought to read it. But don’t dwell on the reason. Coax the reader a little more; keep him inquisitive.
Continue to build. Every paragraph should amplify the one that preceded it. Give more thought to adding solid detail and less to entertaining the reader. But take special care with the last sentence of each paragraph—it’s the crucial springboard to the next paragraph. Try to give that sentence an extra twist of humor or surprise, like the periodic “snapper” in the routine of a stand-up comic. Make the reader smile and you’ve got him for at least one more paragraph.
- Review On Opening Essays, Conference Talks, and Jam Jars.
- Make sure the piece doesn’t open at the beginning of time.
- Make sure the piece doesn’t start with a statement of what I’m going to write about, then a definition.
- Does the opening have tension (paradoxes, unanswered questions, unresolved action)?
- Review the closing sentence and closing paragraph.
- Is it boring? Has it gone on too long?
§ Frontmatter
- Is it a draft?
- Review the title.
- Review the description. (It isn’t just internal! It’s used in search results, when the page is unfurled, and when entry lists include descriptions.)
- Do I pull any features that I didn’t use? Table of Contents? Notes?
§ Metadata block
- Should it have a metadata block?
- Review the summary.
- Review the assumed audience.
- Review the tags
- Is it part of a project or series? Is that in the block?
§ Images
- Does the post need an image? Do any paragraphs?
- Is the image necessary?
- Does the alt text convey the purpose of the image?
- Check the alt text against this W3 alt-text decision tree.
- Check any lightbox image captions. There’s a site bug where Markdown isn’t expanded.
- If there’s a meme or reference to one, do I link to Know Your Meme?
§ Videos
- Does it have a video or link to a video?
- Do I include the length of the video?
§ Table of Contents
- Should it have a table of contents?
- If it’s long enough to need a table of contents, make sure it has an Introduction section.
§ Things I’ve Found (Links)
- Review Simon Willison’s approach to running a link blog.
- Add the names of people who created the thing.
- Is there context about why this thing is worth reading?
- If it’s a video, should I include a quote from it?
- Does it tie to other things I’ve posted?
- Have I proved I read it?
- Should I add a screenshot?
§ Projects
- Do I include an image or a screenshot? (Or an animated one?)
§ Review
- Use all the static checkers to cover broken links and other style things.
- Look at the page with a range of screen sizes.
- Share the post with early readers and ask what they think.
- Review the feed markup.
- Check how the feed entry looks in a reader.
§ Resources
Some of these resources have been used to create this checklist. Others, I still need to review.
- On Writing Well, 30th Anniversary Edition by William Zinsser
- Maggie Appleton’s On Opening Essays, Conference Talks, and Jam Jars
- Simon Willison’s My approach to running a link blog
- Robert Heaton’s A blogging style guide, vol. 2, How to write better sentences
- Adrian Roselli’s “My Approach to Alt Text”
- Tom Critchlow’s “how to write a good blog post” tweet, archived here
Tom Critchlow’s “Vince McMahon Reaction” with “Here’s a quick riff”, “About a line of inquiry that’s alive for me”, “This post poses more questions than answers”, “With some real texture from my own experiences”, and “Here’s a quick drawing I made”.
If this was helpful or enjoyable, please share it! To get new posts, subscribe to the newsletter or the RSS/Atom feed. If you have comments, questions, or feedback, please email me.