Our Guide to Editing a Blog Post

Whether editing someone else’s written work or your own, here are some key steps to take to clean up a blog or article before publishing.

When assigned a blog post to edit, the author should give you a brief description of the following:

• Title and/or topic of the post
• Purpose for writing the blog
• Target audience
• Any specific issues you need to look for

This should all be provided in the GitHub issue. Otherwise, message them on Slack to get this information before editing.

Remember the following goals of a good blog post as you edit:

• Hook and maintain the audience's attention from the title onward.
• Be understandable for the target audience (this depends on what the target audience should already know prior to reading the blog post).
• Be relatable to the target audience.
• Use appropriate tone for the target audience and content of the post.

With the relevant information and the blog goals in mind, follow these steps to complete the editing process:

1) Initial look-over and first edits.
Read over the blog post without making major changes. Take note of the pros and cons that stand out to you. What does the blog post do well that can be replicated in other areas? What areas need improvement? Then, edit minor errors such as spelling, punctuation, or run-on sentences. For substantial edits, comment what is wrong with the highlighted passage. Provide an example of how you would fix it if possible, but don’t rewrite the section unless it’s necessary (this will be covered in second edits). It is up to the author to decide how to take your advice.

2) Second edits.

Before editing again, the second draft should be finished. Sometimes, the first round of edits is sufficient to complete the post, but you often need one more round to fix things you missed the first time. Repeat Step 1, but make sure that you’re focused on what the author has changed. Resolve any comments on areas that no longer need to be edited. Make new edits/comments and rewrite certain passages if necessary.

3) Final look-through.

By now, the final draft should be done, but make sure to read it over once more to be sure it’s error-free and prepared for publishing. Don’t forget about formatting and clarity — sometimes you can’t tell something sounds funny because you’ve read it so many times. Try reading from the audience’s perspective; be intentional with this last look-over.

4) Optional meeting for clarification.

If needed, set up a meeting with the author/editor to go over edits and comments. Prior to the meeting, the author should have at least read through all the edits/comments that have been made. If there are any remaining inconsistencies in the purpose for the blog post, ask for clarification. Editors should help the author start making the appropriate edits to their draft and clear up any confusion about editing suggestions.

5) Attend a workshop.

Weekly workshops with the writing team and the DevRel team will be held. These workshops are not mandatory, but are highly recommended for those who need help writing or editing their blog posts. At least one writer will be present to help those in need. Sometimes, the writing team will give presentations on important aspects of the blog post writing process. Blog post writers can come by with any questions, concerns, or feedback.

Throughout the editing process, you should be looking for (and fixing) these common issues:

• Inconsistencies in tone, formatting, and/or citing of sources:

Your blog will look and sound better if these elements are the same throughout.

• Lack of flow/no transitions:

Transitions make your writing make sense. When you move on to a new topic, alert the reader with a topic sentence introducing the new concept.

• Poor organization of paragraphs and/or sentences:

If you were presenting your article word-for-word, would the audience understand?

• Irrelevant information or filler words:

Avoid words like “truly,” “really,” “just,” “actually,” and “very.”
The idea is to be concise — most of the time, your writing is better after you cut things out. Every sentence should have a purpose. Ask, “does this need to be here?”

• Repetition:

If you read over your draft and find that ideas are repeated in different ways, pick the best-written text and only include the idea once, other than for summarization purposes.

• Grammatical errors:

Try to think about how you say things in conversation to help you translate words to grammatically-correct writing. Think about where you pause in a sentence, for example:
Common mistake: In case you forgot you need to use a comma in this sentence.
Correction: In case you forgot, you need to use a comma in this sentence.

• Errors in spelling and punctuation:
  ‘Their’ vs ‘they’re’
  When using “quotation marks,” keep the punctuation inside the “quotes!”

• Run-on or incomplete sentences:

Break up long sentences into two parts, so more relevant information can be shared in a clearer way.
Run-on: “We will use Python which will teach you how to run this code and create a useful chatbot that can help your company with customer service in order to boost sales.”
Vs. clear and concise: “This tutorial will use Python to teach you how to create a chatbot for your company. Chatbots help to automate customer service, boosting sales and preventing employees from wasting time on FAQs.”

Keeping these general editing techniques in mind, you can improve your writing and create clear and informative blog posts!