View source for Wiki143:Refactoring talk pages

{{For|the policy on refactoring other editors' comments|WP:TPO}}

{{Wikipedia how to|WP:RTP|WP:REFACTOR}}

'''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 [[Wikipedia:Namespaces|namespaces]]).

Refactoring has a number of uses, including:
* Improving the [[readability|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 [[Wikipedia:How to archive a talk page|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 [[Wikipedia:Assume good faith|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 [[Wikipedia:How to archive a talk page|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&nbsp;– a non-preservative refactoring method. However, the community has come to prefer wholesale [[WP:ARCHIVE|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&nbsp;– doing so creates misrepresentations, disrupts the flow of conversations, and makes debates and discussions impossible to follow&nbsp;– 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:

{{anchor|NCC}}{{short|WP:NCCREFACTOR}}'''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 [[Wikipedia:Indentation|indentation]] levels
* Fixing [[Wikipedia:Link rot|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 {{tl|anchor}} below the new heading so as to not break any links to the old one, or use a template that leaves indication of the change which includes the anchor, such as {{tl|Thread retitled}} or {{tl|Section renamed}})
* Reattaching signatures that have been split from the text, or adding "missing signature" templates such as {{tl|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.
* Adding {{t|sticky decoration wrapper}} to [[Wikipedia:User pages#Sticky decorative elements|sticky decorative elements]]

'''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
* [[Template:Collapse top|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 [[Wikipedia:talk page guidelines|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#Linking to a diff|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 [[Wikipedia:Oversight|Oversight]], [[Wikipedia:Revision deletion|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&nbsp;– <code><nowiki><s>text to be struck</s></nowiki></code> produces <s>text to be struck</s>.  This text is still marginally readable on the page, and will show up in page searches.
; Moving text off-page : Material can be [[wp:userfy|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 {{tlx|rf}} to mark moved material.
; Hidden divs, collapsible tables, and templates : A number of tools and templates hide or block text from further editing&nbsp;– {{tl|hidden}}, {{tl|cot}}, {{tl|hat}}, {{tl|archive top}}, {{tl|discussion top}}.  These work by creating [[help:collapsing|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 {{tl|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===
{{shortcuts|WP:Arbitrary break}}
{{see main|Wikipedia:Talk page guidelines#section}}
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 [[Wikipedia:Refactoring talk pages#Significant examples|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 <nowiki>[[Talk:New Imperialism/Summary of archives 7 to 10]]</nowiki>. 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&nbsp;– 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&nbsp;– see [[list of text editors]].  Many scripting languages for text processing also exist; common ones are  [[Perl]], [[Python programming language|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 <code><nowiki>{{in use}}</nowiki></code> 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 [[Wikipedia:Edit conflict|edit conflicts]].

==Significant examples==
Talk pages or talk page sections that have benefited from refactoring:
* [//en.wikipedia.org/w/index.php?title=Talk:Exterior_algebra&oldid=356356089#Exterior_to_what.3F_Ausdehnungslehre_means_.22extension_theory.22.2C_not_.22exterior_theory.22 Exterior to what? Ausdehnungslehre means "extension theory", not "exterior theory"] (conservative refactoring by inserting paragraph titles)
* [//en.wikipedia.org/w/index.php?title=Talk:Geometric_algebra&oldid=372286001#Is_there_a_convention_about_the_order_of_multivector_components.3F Is there a convention about the order of multivector components?] (conservative refactoring by inserting subheadings and paragraph titles)

== See also ==
* [[Wikipedia:How to archive a talk page]]
* [[Wikipedia:Remove personal attacks]]
* [[Wikipedia:Pruning article revisions]]
* [[Wikipedia:Not so arbitrary breaks]]
* {{tl|Inappropriate comment}}

== External links ==
* [[c2:RefactoringWikiPages|Refactoring wiki pages]]
* [http://c2.com/cgi/fullSearch?search=CategoryRefactoring Refactoring category at Wiki]
* [http://www.usemod.com/cgi-bin/mb.pl?back=CategoryReworking Reworking category at MeatBall]

[[Category:Wikipedia discussion]]
[[Category:Wikipedia maintenance|Refactoring]]
[[Category:Wikipedia how-to|Refactoring]]