118Wiki:Edit Summaries: Difference between revisions
Jump to navigation
Jump to search
(Creation) |
(Page start with content from Wikipedia's help file, and discussions from our Discord server.) |
||
| Line 1: | Line 1: | ||
{{118Wikinav}} | {{118Wikinav}} | ||
It is considered good practice to provide a '''summary''' for every edit, especially when reverting (undoing) the actions of other editors or deleting existing text; otherwise, people may question your motives for the edit. Accurate summaries help other contributors decide whether they want to review an edit, and to understand the change should they choose to review it. | |||
You'll find the edit summary box directly below the editing window, and above the "This is a minor edit" and "watch this page" checkboxes. | |||
==Why edit summaries are required== | |||
Because all pages have detailed histories of every change, edit summaries can help make it easier to find a specific change to a page. | |||
Moreover, they make it easier for wiki admins to review the [[Special:RecentChanges|Recent Changes]] list to see what's changed. | |||
Finally, it's just good practice! Edit summaries can help you keep track of what you've already changed and get you in the habit of making smaller, more focused edits – which make your edit history easier to navigate – and saving them more often, as opposed to making expansive changes that are difficult to disentangle if you need to revert. | |||
===Similarities to code development=== | |||
A similar feature to edit summaries exists in the development of software programs. Usually called "version control," these systems ensure that programmers have detailed records of what they've changed and can revert any changes that break their software. "Git" is a popular version control system, for example. | |||
When teaching new programmers version control, these general principles are taught to help them understand the need for good edit summaries: | |||
* A well-crafted commit message is the best way to communicate context about a change to other developers working on that project, and indeed, to your future self. | |||
* Understanding why something happened months or years ago becomes not only possible but efficient. | |||
* A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved. | |||
* Commit messages can adequately communicate why a change was made, and understanding that makes development and collaboration more efficient. | |||
==What should be in an edit summary== | |||
* '''Summarize'''. Summarize the change, even if only briefly; even a short summary is better than no summary. | |||
* '''Explain'''. Give reasons for the change, if you think other editors may be unclear as to why you made it. Citing the Wikipedia policies or guidelines that you feel justified the change may be incorporated into your explanation. | |||
===What to avoid in edit summaries=== | |||
* '''Avoid misleading summaries.''' Mentioning one change but not another one can be misleading to someone who finds the other one more important. You could add something like "and misc." to cover the other changes. | |||
* '''Avoid vagueness.''' While edit summaries can be terse, they should still be specific. Providing an edit summary similar to "I made some changes" is functionally equivalent to not providing a summary at all. | |||
* '''Avoid long summaries.''' Edit summaries are not for writing essays about 'the truth' or long-winded arguments with fellow editors. For discussions, you should use the talk page. | |||
* '''Avoid inappropriate summaries.''' You should explain your edits, but without being overly critical or harsh when editing or reverting others' work. This may be perceived as uncivil, and cause resentment or conflict. Explain what you changed, citing the relevant policies, guidelines or principles of good writing, but do not target others in a way that may come across as a personal attack. | |||
* '''Avoid incivility.''' Snide comments, personal remarks about editors, and other aggressive edit summaries are explicit edit-summary "don't's" of the Wikipedia Civility policy. | |||
==See Also== | |||
* [https://meta.wikimedia.org/wiki/Help:Edit_summary MediaWiki's Edit Summary help file] | |||
{{WikipediaContent}} | |||
[[Category:Help]] | |||
Revision as of 19:56, 15 April 2020
It is considered good practice to provide a summary for every edit, especially when reverting (undoing) the actions of other editors or deleting existing text; otherwise, people may question your motives for the edit. Accurate summaries help other contributors decide whether they want to review an edit, and to understand the change should they choose to review it.
You'll find the edit summary box directly below the editing window, and above the "This is a minor edit" and "watch this page" checkboxes.
Why edit summaries are required
Because all pages have detailed histories of every change, edit summaries can help make it easier to find a specific change to a page.
Moreover, they make it easier for wiki admins to review the Recent Changes list to see what's changed.
Finally, it's just good practice! Edit summaries can help you keep track of what you've already changed and get you in the habit of making smaller, more focused edits – which make your edit history easier to navigate – and saving them more often, as opposed to making expansive changes that are difficult to disentangle if you need to revert.
Similarities to code development
A similar feature to edit summaries exists in the development of software programs. Usually called "version control," these systems ensure that programmers have detailed records of what they've changed and can revert any changes that break their software. "Git" is a popular version control system, for example.
When teaching new programmers version control, these general principles are taught to help them understand the need for good edit summaries:
- A well-crafted commit message is the best way to communicate context about a change to other developers working on that project, and indeed, to your future self.
- Understanding why something happened months or years ago becomes not only possible but efficient.
- A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.
- Commit messages can adequately communicate why a change was made, and understanding that makes development and collaboration more efficient.
What should be in an edit summary
- Summarize. Summarize the change, even if only briefly; even a short summary is better than no summary.
- Explain. Give reasons for the change, if you think other editors may be unclear as to why you made it. Citing the Wikipedia policies or guidelines that you feel justified the change may be incorporated into your explanation.
What to avoid in edit summaries
- Avoid misleading summaries. Mentioning one change but not another one can be misleading to someone who finds the other one more important. You could add something like "and misc." to cover the other changes.
- Avoid vagueness. While edit summaries can be terse, they should still be specific. Providing an edit summary similar to "I made some changes" is functionally equivalent to not providing a summary at all.
- Avoid long summaries. Edit summaries are not for writing essays about 'the truth' or long-winded arguments with fellow editors. For discussions, you should use the talk page.
- Avoid inappropriate summaries. You should explain your edits, but without being overly critical or harsh when editing or reverting others' work. This may be perceived as uncivil, and cause resentment or conflict. Explain what you changed, citing the relevant policies, guidelines or principles of good writing, but do not target others in a way that may come across as a personal attack.
- Avoid incivility. Snide comments, personal remarks about editors, and other aggressive edit summaries are explicit edit-summary "don't's" of the Wikipedia Civility policy.
See Also
