12

As a user, I don't often ask questions (in fact, I believe I have only asked two questions in total across the entire network, excluding meta). However I do a lot of answering, flagging, commenting and of course, editing.

Because I like things to be consistent, intuitive, efficient and definite, I've developed a system of structure and keywords for my edit summaries.

Other discussions on Big Meta and per-site metas make it clear that the quality of edit summaries can be the difference between acceptance and rejection, or lead to grief when somebody hasn't explained their intent or actions quite so effectively.

Finally, if one writes a summary, they can confirm to themselves what they have done, and whether it's (all of) what they were aiming for.

How do you write the summary when you make an edit?

I will write an answer that describes the system and keywords I use. Other answers that extend this system, or better yet describe alternatives, will help people to understand what others are trying to say when they write an edit summary, as well as how they might write a better summary themselves.

0

3 Answers 3

12

Your edit summary is aimed at three slightly different audiences:

  • reviewers, if you can only suggest edits. You want to convince them to approve your edit. If you are adding material that was in the comments, say so - normally just adding material doesn't get approved. If your change is minor but critical, this is where you explain that criticality so the suggestion isn't rejected as too minor.
  • the OP, either in their role as reviewer of your suggested edit, or as a notification-clicker who wants to know what happened to their post. A comment that teaches the site norms or explains a seemingly arbitrary change isn't strictly required, but if you're taking the time to fix someone's post, you can probably also take the time to explain to them why this is a fix, not vandalism
  • posterity, when people look over the revision history. By far the smallest case even though it's a long tail. It probably doesn't matter what you say here, but I would encourage focusing on why over what - we can all see what is changed, the comment is a chance to add something more. I typically only care about posterity when I'm editing my own posts, and then I explain my thinking.

Use caution when your comment involves enforcing a norm newcomers are unaware of. Say you remove "Hey everyone, this is my first post, I hope it's ok" at the start of a post and "Thanks in advance, hope you can help, this is really urgent for me" at the end. Your edit comments could be

The first is likely to spark an argument or at least hurt feelings from the OP. The second doesn't help since people who include such content in their posts don't generally recognize the phrase "meta content". The third is backed up by site policy, though that may not reduce hurt feelings and instead encourage "site policy is stupid and rude" first meta postings. The fourth tells the OP what's in it for them and why the edit made their post better. (It's also easier to do than the third since you don't need to go find a link to prove you're right.)

I put the most care into edit summaries on sites where my edits are reviewed. I try to explain a why and a benefit to the OP on my other edits, but I don't always do so. And if I have nothing better to say than "spelling and formatting" on a site where the edit summary is optional, I leave it out. Such summaries add no value, so I spare myself the trouble of typing them.

6

I think writing a good edit summary that is concise and self-explanatory is important.

Personally, I would usually describe what I changed in short sentences, for example:

  • Formatted code

  • Formatted error messages

  • Corrected spelling/ grammar

  • Updated dead link to working ones

  • Removed noise

  • Improved general formatting

I do combine them sometimes:

  • Formatted code & corrected spelling

Basically, the summary should summarise what you have edited, so that the OP would understand why the post was edited and such keep in mind the mistakes they made.

I don't think edit summaries should be very long or very precise and definitely not in complete sentences, for example:

  • I have edited paragraph 2 to display image inline and also edited paragraph 3 to remove blank lines.

By just editing without leaving a edit summary, it would sometimes create a misunderstanding on why the post was edited.

So, I've described how I usually craft my edit summaries and what I think is useful to the general community.

4

From my personal experience, be precise. There is no definitive guide for putting the comments, you just need to communicate to the reviewer (including OP) in case, the edit is not so easy to understand.

Try to put the things you edited in two or three words and use a comma separated list, like

Fixed broken links, corrected grammar & spelling, re-tagged.

Avoid writing overly-long edit messages. If the edit is good, it generally speaks for itself.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .