Encouraging Wiki Refactoring

More people need to be involved in WikiRefactoring. How do we encourage them to get involved?

Wiki refactoring is difficult work. It takes a lot of time and energy, and since you're constantly changing other people's writing, it can be politically touchy as well. Furthermore, there isn't much of a personal interest in doing so; unlike writing wiki, refactoring wiki is largely anonymous.

So, then, how do we encourage people to refactor?

By encouraging praise

Since I started doing lots of refactorings, I have received a bunch of ThankYou notes on my page. Those definitely helped. Maybe other things like this would be a start?

By appealing to altruistic motives

Another thought: The closest parallel I can draw between Wiki refactoring and another activity is not actually programming, but politics. In consensus-based politics, you have to figure out where everybody stands, assure everyone their input is valued, and then find middle ground. You have to do this in Wiki refactoring, as well. This is hard work. But with politics, the benefits range from the altruistic (you get to help your community and feel like a Good Person) to the selfish (you get to be a big powerful person who's on TV a lot). Wiki refactoring has lots of altruistic benefits, but nothing selfish.

By removing stigma and inappropriate criticism of Refactorers

Also, I think this is the kind of activity that programmers usually avoid. It's a matter of temperament; programmers tend to like precision and clarity. It's often part of why they got into computers in the first place. Compromise, feelings, respect - these dynamics are all really messy and imprecise. But you need to pay attention to them if you refactor a page. (I also think this is why so many programmers are libertarians.)

-- FrancisHwang

One common thread I've seen so far is that refactoring is too anonymous. We need a way to promote the authorship-ness of refactoring.

Another is that it's too difficult. I think organizing and generating pages about this would be helpful. We also need to remove the WikiOnWiki stigma of discussions of refactoring if this is to work.

By starting small, gaining confidence and competence

As of this writing, there are a number of WikiGnomes wandering around doing lots of small maintenance: deleting test pages, adding category tags, fixing people's grammar and spelling, etc. Such work is valuable, and for that they should be thanked. Such work can be a starting point. In such activity the would-be refactorers will gain in confidence and skill.

There are a number of pages here that need much more drastic refactoring. Some pages will need to be merged, distilled, split, or reorganized. In addition to the correction of spelling the correction of focus and concentration of thoughts and page flow will improve an otherwise sprawling, and unfocused page.

While some have been doing some of this more drastic work, to ensure a diversity of view and opinion, there should be many more people attempting it. While this involves a significant investment of effort, thought and courage, and may at times lead to controversy, the results can be beneficial to the refactorer as well as the page.

Perhaps we need a documentary entitled WikiGnomeGrowth?, following a young gnome through the stages of her/his career.

Those who are successful in the refactoring effort might share by composition of pages of how-tos, possibly charting what they have learned in the process of document refactoring? Perhaps by writing a paper, article or even a book? This has already been done for source code by Martin Fowlers in a book. What about something comparable for documents. There certainly are patterns/practices which might be written/shared. Why not list methods, how page is found requiring refactoring, the method of multipage refactoring, (work alphabetically, recent-changes, following links etc.)? What makes the task easier?

What I see in my personal wiki is an emergence (hope that's not a buzzword) or filtering of useful topics which have higher linkage (a la hubs), get visited more and are kept up to date but that unlinked pages fester away untouched. Maybe a collaborative refactoring could be done with discussion and learning of the techniques used, something to encourage WikiGnomeGrowth?.

Over tea this morning I find there is already a list of patterns...

WikiRefactoring http://clublet.com/c/c/why?HowToConverseDeeplyOnAWiki

so I add that link here and also changed the first line of this page to provide a link to similar page (for us aspiring gnomes). Reading those notes, though, is rather humbling as it seems there are many who've aspired to this before, perhaps there's a list of anti-patterns on why it failed? Skulking in the shadows of the giants who've gone before...

WikiRefactoringStories -- some nice learnings WikiReductionists -- being aggressive in condensing content BigWikiFireOfDoubleOught -- allegory GoodWikiCitizen -- things to remember CategoryWikiMaintenance -- dynamic list of relevant pages

In the realm of BlackaddersMap, we may feel intimidated -- anon again (still interested and still reading).

By pointing out that success is more frequent than failure, and that even simple methods and rules can prove effective

Page refactoring here has probably succeeded more than it failed; the only reason it might appear otherwise is that failures are visible, whereas successes aren't. The best refactorings are those that seem natural, perhaps even inevitable.

Let me offer my methods as one example; certainly they aren't the most effective possible, but they seem to work somewhat. I have, basically, four page-refactoring moves:

Extract: Take text from one page and create a separate page.
Merge: Take text from one page and merge it into a pre-existing page.
Regroup: Rearrange text on a page until content is well-grouped by subtopic.
Distill: When a subtopic is too big, and contains a lot of redundancy, rewrite it to say the same thing with less words.

I almost always start with a page that is too big (my rule of thumb is ten screens) or too small. Usually pages that are too big, and I'm trying to whittle them down. One of the things I notice is that when things get chatty and pages get big, there is a tremendous amount of redundancy. So I end up regrouping a lot, and then when a section gets pretty big (my rule of thumb is one screen), I rewrite a lot of the section, trying to retain everything essential to the discussion.

I try to move slowly. Most of the pages that I've refactored, it takes maybe 5-10 separate passes to get it all done, so the work can be a little exacting. (I usually save local copies on my PowerBook, which lets me keep track of what to do next.) But that pace seems essential to me to give people time to chime in if they have concerns about where a refactoring's going.

Does that help? -- francis

Finding Pages needing refactoring

Yup, how about finding the pages? Do you methodically go looking for them; stumble across them while reading recent-changes; add tags/badges (e.g. please-refactor-me) for rework later? Do you think there might be some admin-tools (perhaps indexing by page size, date last modified) that might help find the crufty old stuff?

I find pages by just reading, and then one day I came across a page that was way too big. (They're not really hard to find; wander around and you'll hit one eventually.) My general rule-of-thumb is that there's no good reason for a page to be longer than ten scrolls. If you start there, you'll have plenty to work on for a while.

This work tends to grow, also. One thing that happens is that you'll decide that a bunch of text would fit better over on another page, but then you look at that second page and realize that it was already too long, and you just went added more text ... Presto, all of a sudden you've got two pages on your list. -- francis

In the spirit of FixYourWiki, I often find pages by looking at backlinks from my HomePage. Oftentimes I find I've contributed to some sprawling ThreadMode discussion that has since cooled down and desperately needs refactoring. My goal here is to eliminate all my signatures from the threads (I always sign ThreadMode), so that the only place my name appears is the Contributors list.

I also find some pages through OrphanWikiPages. These are often very hard to refactor, as I'd like to link them into the rest of Wiki content as well. I try to Google for the words in the hopes they've been mentioned (unlinked) on other Wiki pages, but I've yet to have that turn up anything.

Then there are the pages that I know need refactoring, because I remember the huge discussions from RecentChanges. I'll let those cool for a month or two, then once I have a big block of time, I can start refactoring. -- JonathanTang

One place you might find candidates for refactoring is to look at pages that have had time to settle down, such as those around 12 months old as in lists such as RandomPages and ChangesInWeek?Foo.

Another thought: Refactoring a page is an excellent way to learn about what it's describing. And I think the highest aim of this or any other Wiki is to be deeply instructive. A good rule of thumb, then: Every time you think yourself thinking "I would've learned more from this page if it were well-factored", you've discovered a candidate.

Contrast this with methods of selecting refactoring targets that have little to do with the content of the page, such as how "settled" a page is, or whether it's been tagged with one of those "fix me when you get around to it" tags such as RefactorMe. RefactorOnlyTheOnesYouWantToKeep. Refactoring is a process of discovery for all involved - refactorer included - so even though it's careful work, it can also be tremendously instructional. It can even be enjoyable, once you get over the jitters of doing it. Refactoring shouldn't be viewed with the same irritation as cleaning out your cat's litter box. If the page is outstanding you might also add it's link to the list page ReallyValuablePages.

The natural result of people refactoring the pages they want to is that those topics that are of most interest to this Wiki will be the most concise, pithy, witty, and wise. The implications of such a development are quite powerful. -- francis

For pages on which to exercise your refactoring skills, see RefactorByMerging and PagesToRefactor.

Single edit refactorings

From WardCunningham's page: "The single most common edit I do is to place related comments together."

Another is to head the related comments with bold text highlighting their commonalities.

By encouraging those hesitant to start with topics and subjects familiar, on pages related to what they know best

Is there anybody here on WardsWiki who would like to take on this sort of work, but has hesitated in doing so? -- FrancisHwang

I hesitate a bit when reading phrases like "nasty thread-dripping page" and "drastic refactoring". It seems like you consider this the pages that really need to be refactored, and that others aren't important. I don't think any new refactorer (?) would want to start on those pages. I started editing on smaller pages, and I'm slowly trying to refactor some larger pages. As I said on WhyNotEnoughWikiRefactoringHappens?, refactoring is different, it's a skill we need to acquire. Being asked to start on the hardest pages isn't exactly encouraging. -- JohannesGijsbers

Johannes, it was not my intention to dismiss the work of people who are beginning. In fact, I'm quite happily surprised by the BarnRaising spirit that seems to have been discovered by a lot of people in the last few months. I was just wondering why larger page-refactorings seem so daunting to some people, and what advice & encouragement could be offered to people who were thinking about taking on bigger tasks. I wouldn't necessarily encourage people to start on the hardest pages if people find those tasks too daunting -- on the other hand, I'm still not sure why people find any page-refactoring that daunting in the first place. -- francis

I believe social status here is determined by the value of your contributions. Social status is an important factor in wanting to do refactoring (or anything else) right. When I'm not sure my contributions are up to the standard (WhyNotEnoughWikiRefactoringHappens?), I won't make my contribution. As refactoring is the hardest 'job' on Wiki, it seems logical that less people believe they can contribute up to the standard. -- JohannesGijsbers (WikiSuccessCanInhibitNewWriters)?

Encourage the important, appropriate, and thoughtful use of categories as a valued, important, and focused RefactoringActivity?

Categorizing Appropriately is an important means of WikiRefactoring, particularly for those concerned with being able to easily navigate, following themes, removing the tendency of readers placing all the focus on what is in RecentChanges or RecentEdits. This is also a way to reduce the number of OrphanPages. It would make sense that ReallyValuablePages would have AtLeastOneCategory?. It can be also a way to focus on the pages that are within the scope and focus of this wiki. This kind of WikiGnome RefactoringActivity? should be encouraged. There are those of a contrary view who see categories as waste of effort and space. If we are to encourage the readers and participants to Go to the recesses of this wiki and discover the value of the many seldom read gems, it would be helpful to encourage the use of Categories and other mechanisms such a FindPage, LikePages, and VisualTour, and so forth.

Follow the software pattern: Refactor, Edit, Refactor

The problem we have is people not cleaning up as they go. Don't just append to debates, reword, condense, add your comment, and reword and condense.

CategoryWikiMaintenance CategoryWikiRefactoring