Wikipedia:Refactoring talk pages

This help page is a how-to guide.

It explains concepts or processes used by the Wikipedia community. It is not one of Wikipedia's policies or guidelines, and may reflect varying levels of consensus.

Shortcuts

Refactoring is a redrafting process in which talk page content is moved, removed, revised, restructured, hidden, or otherwise changed. It applies only in contexts where editors make signed statements (such as in the Talk and User talk namespaces).

Refactoring has a number of uses, including:

Improving the clarity and readability of a page
Removing off-topic, uncivil, unclear, or otherwise distracting material
Restructuring of discussions for clarity
Relocating material to different sections or pages where it is more appropriate

Refactoring is more assertive than copy editing, but less substantive than archiving. Like copy editing, it always preserves the original editor's meaning and intent. Like archiving, it may hide material from immediate visibility. It should be used as a tool to separate unnecessary material from a discussion on the fly, without waiting for formal archiving of the entire discussion.

The term "refactoring" is adapted from code refactoring in computing, where code is restructured (to improve its quality) in a way that does not change the operation of the program.

Good refactoring practices are an important part of maintaining a productive talk page. Discussion pages that are confused, hostile, overly complex, poorly structured, or congested with cross-talk can discourage potential contributors, and create misunderstandings that undermine fruitful discussions.

Refactoring should only be done when there is an assumption of good faith by editors who have contributed to the talk page. If there are recent heated discussions on the talk page, good faith may be lacking. If another editor objects to any refactoring that was performed, those changes should be reverted. Nevertheless, if the page is larger than the recommended size, then archiving of the talk page, or sections within it, without refactoring can still be done.

Refactoring overview

Earlier in Wikipedia's history, and particularly before 2006, talk page content was summarized to conserve space – a non-preservative refactoring method. However, the community has come to prefer wholesale archival of talk page discussions, since archiving preserves a fuller record of discussion, does not lead to misrepresentation (accidental or disruptive) of other editors' opinions, and conserves material that may be useful in the future. The same principle has come to be applied to refactoring more broadly.

As a rule, editors should not edit each other's comments in ways that affect meaning – doing so creates misrepresentations, disrupts the flow of conversations, and makes debates and discussions impossible to follow – but cases exist in which an editor's comments need to be removed from the flow of conversation because the comments themselves disrupt the flow of conversation. Loosely, the following types of refactoring are legitimate, with the listed caveats:

Non-contentious cleanup – anything where you are sure that the other editor will thank you for the effort, rather than getting angry.

Adding missing topic headings and attribution
Correcting indentation levels
Fixing dead links
Fixing technical matters of wikitext formatting, tables, templates, broken links, and the like
Improving headings with typos or which are not descriptive of the content (use {{anchor}} below the new heading so as to not break any links to the old one)
Reattaching signatures that have been split from the text, or adding "missing signature" templates such as {{Unsigned2}} to comments that users have forgotten to sign
Other minor fixes without changing someone's words. Keep in mind that WP:TPO says not to correct other users' spelling or grammar without their permission.

Restructuring – should be done with care to avoid changing meanings.

Adding new sections that split an editor's comment into separate points
Moving a comment to a more appropriate place in the discussion
Moving or copying a comment to begin a new discussion in a different section

Pruning text – should only be done with the original author's consent, or with good cause under policy.

Removing, striking or hiding personal attacks
Hiding redundant, outdated, or otherwise superfluous material from view
Relocation of text to different pages where it is more appropriate

How to refactor

Following Wikipedia's talk page guidelines, editors are encouraged to remove any content that is not appropriate. A link to the talk page history should be added if the removed text was part of discussions by other editors. See WP:Diff for guidance on creating a link to the page history and WP:Talk page guidelines#Behavior that is unacceptable for guidance on inappropriate talk page content.

There are several tools and techniques available for refactoring material:

Deletion: Editing and deleting the text completely. Except for non-contentious fixes, this should only be done by the editor who wrote the material or by a sysop or bureaucrat with legitimate cause. Unless a sysop uses Oversight, RevDel, or a page has been deleted entirely, the deleted text will still appear in old revisions of the page.
Strike-outs: Using the HTML strikeout tags – <s>text to be struck</s> produces ~~text to be struck~~. This text is still marginally readable on the page, and will show up in page searches.
Moving text off-page: Material can be userfied or moved to a different page where it is more appropriate. If the refactoring is later reverted, the moved material should be deleted on the pages it was moved to, to prevent proliferation of the text. It is helpful to use the template {{rf}} to mark moved material.
Hidden divs, collapsible tables, and templates: A number of tools and templates hide or block text from further editing – {{hidden}}, {{cot}}, {{hat}}, {{archive top}}, {{discussion top}}. These work by creating collapsible elements. Material collapsed in this fashion does not show up in page searches unless it is in an expanded state.

The tool or technique used should be chosen according to the particular needs of the material.

The creation of an FAQ is recommended for any points that are likely to be repeatedly raised and refactored. Existing material should be generalized appropriately and reformatted into a simple question/answer format so that later editors can have their concerns satisfied without raising the question again. Likewise, lengthy ongoing discussions might benefit from template refactoring with a summary. The {{quote box}} template can be used to provide a floating summary box next to a refactored discussion, or a comment may be added at the bottom (or sometimes the top) of a section.

Resectioning

Shortcut

WP:Arbitrary break

In some cases, discussion should be broken down into new sections or subsections. This is useful when a section becomes overly long, or when conversation begins to diverge into a number of separate points. Resectioning may help both readers and participants understand the flow of the discussion and help them find relevant parts of the text.

For long discussions, participants often insert arbitrary breaks by adding a new subsection heading. In fact, such breaks are often given headings like 'Arbitrary break' or 'convenience break', with an index number to distinguish it from other arbitrary break headings. Discussions that cover multiple points or become more complex, by contrast, may benefit from the creation of subsections to address different points, or in extreme cases by splitting off sections of text into entirely new sections. It may be necessary in these cases to reorganize large swatches of text, and if so care should be taken to ensure that no comments are taken out of context or lose connection with the original point they were addressing. It may be advisable to copy sections of text rather than move them (adding a comment that refers back to the original text), to duplicate the original author's signature across different points that have been moved to different sections, or to begin the new section with a parenthetical statement explaining the original context of the comment.

See examples below.

Concerns

These concerns should be considered when refactoring:

Refactoring may cause confusion if improperly applied to an ongoing discussion; an editor should take great care to preserve all such discussion and all relevant details to its context.
Editors should be conscious of the newcomer's perspective; one should not remove content that would benefit an editor who had not yet read the page.

Be aware that not every editor will agree with your refactoring or even of the refactoring concept in general. Provide links to the original, uncut version, so others can check your changes, and if necessary go back to the original to clarify what an author actually said. This combination of refactoring and archiving will often prevent complaints that information was lost. Make it explicit that you have refactored something so no one is misled into thinking this was the original talk page.

If you think people may object to their discussion being refactored, make your summary on a different page. Rather than reducing archives 7 to 10 of Talk:New Imperialism, create a new page entitled [[Talk:New Imperialism/Summary of archives 7 to 10]]. Link this to the top of the appropriate archives, and to the current talk page. This gives newcomers the chance to get a quick understanding without the risk of losing what has gone before. Having a linked archive can help satisfy both those who feel their words must remain intact and those who want a neat summary.

Advanced tools

Simple refactoring can easily be done with standard Wikipedia browser editing, but if you are faced with a particularly complex or tedious refactoring job, an advanced text editor or any of an assortment of scripting languages can be immensely helpful. Basically, any tool that has extended find and replace features, regular expression capabilities, or programmatic text processing will become your best friend. Alphabetizing material, sorting sections into chronological order, changing multiple links, restructuring large tables – these tasks can be painful and time consuming to do by hand, but can be accomplished in a matter of minutes programmatically. Most high-end 'Office'-type text editors have advanced text editing capabilities, and many light-weight but powerful text editing applications are available – see list of text editors. Many scripting languages for text processing also exist; common ones are Perl, Python, Unix shell scripting, and AppleScript.

For long refactoring jobs, it may help to tag the page(s) being refactored with Template:In use. Simply add {{in use}} to the top of the page(s). This will alert other editors to the fact that the pages are under construction, and should help minimize edit conflicts.

Significant examples

Talk pages or talk page sections that have benefited from refactoring:

Exterior to what? Ausdehnungslehre means "extension theory", not "exterior theory" (conservative refactoring by inserting paragraph titles)
Is there a convention about the order of multivector components? (conservative refactoring by inserting subheadings and paragraph titles)

External links