Why Refactor Wiki Pages

Purpose: To define Wiki page refactoring, enumerate acceptable refactorings, and discuss candidate refactorings.

If refactoring code means improving its structure without changing its apparent behavior, refactoring a Wiki page would mean making it easier to read without changing its meaning.

Forces:

Thread mode
- Pages seem to grow most naturally through thread mode.
- Thread mode is hard to read.
- The value of the sequence decays with age
Signed entries
- People are less likely to change signed entries
- People are more likely to respond to signed entries
Entry demarcation
- Entries can be separated with horizontal lines
- Entries can be separated using italics
- Entries could be separated with bold but they aren't
- Comments could be entered using square brackets [] but they generally aren't
- Topic changes could be marked using titles (in bold)
Page layout
- Large pages make information more inaccessible.
- Some pages have a body of text at the top with thread mode comments underneath
- New pages make information very accessible
Changes
- Changes made in the middle of a page are least likely to be seen
- Changes made to the start of a page are more likely to be seen
- Changes made to the end of a page are most likely to be seen
Norms
- We don't have very many

The lack of norms might be the biggest problem. I've been making changes to pages lately but I feel shy about doing it because I'm afraid that someone will be offended by my changes. It would be nice to have a list of changes that it was okay to make to a page so that those of us who are willing to do housekeeping will be comfortable doing it.

To that end allow me to propose the following game: I'll set up some sections below separated by horizontal lines and titled in bold. I'll make one for refactorings that seem to be okay and another for refactorings that are under consideration. I'll also create a section for each refactoring that is under consideration to be used for discussion. Here are the rules. Anyone can promote a candidate refactoring to acceptable by moving it to that section and creating a new page for it. This page should explain how to do the refactoring, why it was deemed acceptable and should also note any objections to it. This information should be extracted from the thread mode discussion but that discussion, including its attributions, should be discarded. Add a new refactoring by appending it to the candidate refactorings list and adding a new section for discussion at the bottom of this page.

If you don't like the rules you can change 'em.

Please see http://refactorwiki.sourceforge.net for a component which eases moving pages and their links in a wiki.

I am thick, as always. After reading this page I do not see the Why explained.

Anyway, I refactor pages of interest because it is a SharpenTheSaw exercise, it helps me to have a deeper connection to the topic on hand.

The why for refactoring can be very subtle. I have started out on a simple exercise of sorting out some confused backlinks and found that there are other pages which relate and that there is work to be done sorting out the related categories. -- JohnFletcher

CategoryWiki CategoryWikiRefactoring