User:RainerBlome/How to write good edit summaries

This is my personal opinion on the purpose and good use of edit messages. Consider it a draft essay. I have searched for a similar essay, but have not found one (but see links below for what I did find).

Rationale

Besides writing new changes, Wikipedians constantly process existing changes. Authors and others read and evaluate changes, search for them, sometimes revert them etc.

In my view, the main purpose of edit summaries is to minimize the total effort needed for Wikipedians to process changes. A good summary reduces the time others need to spend processing the change.

Over time, the sum of the time that people spent reading a change may exceed the time that the author spent writing it, simply because the change is being written only once, but may be processed an indefinite number of times.

Let's minimize that processing time.

How to

This section here mentions only some basics in order of priority. For more information, see the official How to write an edit summary.

If possible, use the "edit" link beside the section title, instead of the Edit button at the top. This will auto-fill the edit summary with at least the section title. This lets others know where in the article you edited.

Describe the purpose of your change leading with one word like "Add", "Remove", "Reference", "Simplify", "Clarify", "Fix", "Expand" or similar. Then explain your change in a few more words.

Prefer to explain the effect of your change, instead of how you did it. For example, write "Align columns of XYZ table" instead of "Add class=align to XYZ table."

Use imperative mood.

• This is slightly shorter than past tense ("...ed") or present continuous ("...ing").
• It is sort of an established convention among people who use version control tools, for example software developers[1] and document editors. Having to write such summaries for their version control tools, they have experience with having to communicate the purpose of changes in a short form, and have found the imperative mood to be a good fit.

Even though the Help article linked above mentions abbreviations, they are not recommended. They make edit summaries hard to understand for people who do not regularly use the abbreviations, possibly costing Wikipedia authors time instead of saving time (see rationale).

Linking in summaries

If you are referring to a particular past edit, add a hyperlink to the change. Use wiki link syntax to do this, for example Special:Diff/1061109290. This is much better than copying the complete URI like https://en.wikipedia.org/w/index.php?title=User:RainerBlome&diff=1061109290. In particular, the wiki link syntax also works in edit summaries, while hyperlinks do not work there.

To refer to a change in another wiki, try prefixing a namespace: For example, en:Special:Diff/1061109290 refers to a change in the English Wikipedia.

Similarly, to refer to a specific version, wiki link syntax is Special:Permanentlink/23265159.