How do I write a good edit summary?

Question

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.

Answer 1

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

• none (if you're allowed to just edit; you'll get an autogenerated "removed xyz characters")
• removed meta content
• removed salutations [link to Are taglines & signatures disallowed? or What's wrong with using polite language in questions? ]
• ensured actual question shows first in preview, sharpened focus

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.

Answer 2

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.

Answer 3

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.

Answer 4

Keywords and keyphrases are listed in the order they are most commonly used. This is also the typical order in which they are included in an actual summary. The less common shorthand summaries may also be extended for precision.

• Sp/Gr or Sp/Gr/Synt - spelling and grammar; spelling, grammar and syntax. Used when making corrections to the language used in a question or answer. This includes misspellings, punctuation and general minor typography. Almost all my edits include this.

• Readability - for when the structure of the question or answer creates difficulty for the reader in following its progression of thought, or when superfluous commentary is included which is not necessary to the question and makes identifying the actual question difficult. Often used to counter the possibility of flags and close-votes for "unclear what you're asking".

• Tags - for when inappropriate tags are removed or reasonable tags are added.

• Title - for when the title has been adjusted, either to make it more precise or to make it consistent with the question body, or when correcting issues that would be considered Sp/Gr/Synt or Readability changes.

• Clarity or Clarification - for when a question is initially unclear but comments or discussion have found out what is meant to be asked about, and this explanation is being incorporated into the question.

• Formatting - for when the markdown, including links and images, in a question or answer are being removed or added or fixed.

• MathJax - for when MathJax or mhchem formatting is being altered, in order to differentiate from general markdown changes.

• Terminology - for when the correct phrases or words are missing or the wrong phrases or words have been used. This occurs especially in a technical context or where the commonly understood meanings lead to a question or answer making no sense.

• Removed [brief name of content] - for when text or other content is removed due to policy or best practise.

• [specific comment in context] - for when a specific change has been made, which nay not fit well under a previous description, that would still be a significant change to the content of the question or answer.