Refactor By Condensing Conversation

An alternative to ConvertThreadModeToDocumentMode. Use those techniques in RefactorWhileRespectingSignatures which preserve signatures to make a conversation more concise, so that the most essential points stand out better for future readers. Do not group signatures into a contributors list but feel free to retain them on condensed contributions.

Recently Wiki hasn't been sure how, where and whether to do this. There have definitely been some refactorings of this type in the past, however.

We should UseRealExamplesForWikiOnWiki here.

Examples - positive

SoftwareCannotBeModeled - see next section.
The first four sections of UnitedStatesOfAmerica had been very nicely cleaned up by persons unknown since I last looked at it a couple of months ago. Only small changes and "pruning" deletes made, but ones which considerably reduced the sense of bad temper and argumentativeness that had been there previously. I don't have a previous copy but reduction of unnecessary unpleasantness without loss of signal is key to great refactoring. MaximumRespect to someone. -- RichardDrake

Comments on refactoring of SoftwareCannotBeModeled

See EgSoftwareCannotBeModeled for before and after.

: All these condensing and refactoring suggestions... take a look at SoftwareCannotBeModeled for an extensive sample refactoring job, and comment - did it get better, did it get worse, and how? -- AlistairCockburn

Well done Alistair. More detail may or may not follow.

[The following was Alistair's response to a note on his home page, now lost. Not sure if this belongs here or on ConvertThreadModeToDocumentMode. It certainly summarizes some of the practical difficulties (not so say confusion) of the person who tries to refactor large Wiki pages.]

To me, wiki is a sand dune, always shifting. I don't count on anything staying in one place here. Personally, I always look at the first screenful and the bottom. Changes in the middle are really tiresome to find.

If a page is long and has been refactored a few times, it gets almost impossible to read, because people add in the middle or at the end (see SoftwareCannotBeModeled). So my feeling is:

) the original form indeed has useful context,
) The refactoring idea at the top Q->A is good (and you don't need the word "contributer", you just transfer their name along with their text),
) Once the page gets refactored AND long with additions going on in multiple places, you're lost. There is no context, no easy way any more.
) Don't put refactorings near the top; put them IN the top section, so regular readers can see them in the first screenful, e.g. refactor to have a Q/A section at the top where we can quickly check for growth, see SoftwareCannotBeModeled

-- AlistairCockburn

History of this page and discussion

This page consisted of the words "See ConvertThreadModeToDocumentMode" for six months from 16th April 2000. The end result may have reflected a common belief about WikiRefactoring: that the best way to condense conversation is by converting thread mode to document mode.

I wrote this page and later found it to be redundant with ConvertThreadModeToDocumentMode and so moved the relevant portion there (as I recall) and left a pointer. I don't see the problem, there's a pointer to a pointer. If someone doesn't like it the thing to do is to change the original pointer to ConvertThreadModeToDocumentMode instead of RefactorByCondensingConversation. -- PhilGoodwin

ConvertThreadModeToDocumentMode is the wrong name and has the wrong content for Alistair's effort. As a single redirect, the page left a ReferentsOnWiki problem that must have been confusing to people, whether reading Alistair's work or looking for the shared wisdom of Wiki in these tricky, controversial areas.

AlistairCockburn clearly takes a broader view of what WikiRefactoring can be. Look closely (EgSoftwareCannotBeModeled may help). Did this example of refactoring by Alistair turn SoftwareCannotBeModeled into pure DocumentMode? Was it introduced by a key DocumentMode summary followed by messy old ThreadMode? I think not.

Most importantly, did the fact that Alistair didn't seem to follow the guidelines in ConvertThreadModeToDocumentMode make his attempt at refactoring worthless? Not for me it didn't. Nor indeed in his excellent summary in MethodOrMethodology, where Alistair put some fine reconstituted words into my own mouth.

On the previous version of RefactorByCondensingConversation Alistair explicitly asked for feedback on this time consuming piece of refactoring. This plea was moved to ConvertThreadModeToDocumentMode and is now back here. Nobody it seems bothered to reply. The silence gives a valuable clue to the very low quality of navel gazing in the last year. How many pages of theory (document mode) and argument (thread mode) about Wiki refactoring, reducing and editing have we produced since October 1999? Without bothering to look at the details of this or perhaps any other example? Of course, to analyse and UseRealExamplesForWikiOnWiki is hard, really HardWork. In comparison, as WardCunningham said in HardWork, adding text to Wiki is easy work.

So to make it easy for ourselves we prefer to generalize. For generalize read waffle. For waffle read pontificate and argue. For pontificate and argue read all the self righteous indignation that went with the worst political power struggles of the most corrupt prelates. (I'm thinking "The Borgias" here, not more recent, humbler vicars of Christ. Read Erasmus of Rotterdam on the subject if you want some really witty and caustic narrative on the subject.)

The refactoring examples and discussion triggered by IrrevocableThreadMode were an excellent step in the right direction for me. Thanks to "Robert De Niro" and the rest of the cast there. But the effective suppression of AlistairCockburn's view of what refactoring of ThreadMode should be like and the ignoring of his excellent example and desire for feedback, for six months to a year, need I think to be faced up to. As do its consequences. -- RichardDrake

All that happened is that Alistair made some changes that nobody commented on and that I combined two pages that I thought were redundant (by content, not necessarily by title). I think that you have made a mistake here in making a (very long) ThreadMode contribution when you could have been more effective by taking action. You could have restored this page, for instance, or (better) some portion of it. -- PhilGoodwin

The only thing of value in the previous version was Alistair's plea and the name of the page. (The other bits were not PlainEnglish and had -- fp attached.)

Or put in your own version of what you think it ought to have been. Your own ideas on "distillation" are, in my view, a more distinct and well developed departure from that idea than anything that's appeared on this page before. I would be happy to see a fresh start on this page, with a PortlandForm OpeningStatement and ConvertThreadModeToDocumentMode discussed in its summary.

Thanks. Begun.

There were at least five issues raised for me by all this.

ReferentsOnWiki consistency problems are often subtle and have to do both with the apparent PlainEnglish meaning where a link occurs and the content then found within the page. In the old state if RichardDrake had said (as I believe) "It's often better to RefactorByCondensingConversation than ConvertThreadModeToDocumentMode" it would have made a lot of sense as a sentence until you looked inside the referents. This sort of thing is to be avoided and you just provided a really great example!
the distance between our DocumentMode about editing (at the top of ConvertThreadModeToDocumentMode for example) and what Alistair was doing. The DifferenceBetweenTheoryAndPractice worries me right across this area. We specialize in generalities. RefactorWhileRespectingSignatures now looks a bit closer to the real McCoy, from my own biased perspective.
the implication of "See ConvertThreadModeToDocumentMode" that converting to document mode is the only way to condense ThreadMode.
because people weren't focusing on real examples, the ethics of editing Wiki has been over-simplified, to put it mildly. Among other things, the ethics of people who have spent enormous amounts of time seeking to improve Wiki have been impugned this year. Even if this had all been done in a moderate tone (not quite how I remember it) and with extraordinarily pure motives it constituted a powerful weapon of persuasion to follow one group's view rather than another. When the ethics weren't based in the detail of real examples but in hearsay they could be manipulated. I would much prefer that this never happens again on Wiki (if it did).
(by far most important) the need to say a lot less about general principles and ethics and a lot more about specific examples. Otherwise our theories and instructions will I fear prove worthless and impractical. This is extremely hard though. For one thing, where are the more difficult aspects of multiple page refactorings discussed and exemplified around here? I've just been dealing with that very issue for the upteenth time with this page, RefactorWhileRespectingSignatures and ConvertThreadModeToDocumentMode.

-- RichardDrake

Examples don't do it for me unless I see the instructions, but the always seem to make the instructions better. Your points here seem to be that these sorts of pages contain too many generalities and too few examples. I agree. Let's add pointers to examples whenever we can find them and invent short ones as we can. I think I did something like that on UnethicalEditing and it worked out well. -- PhilGoodwin

Yes, there were some good short examples there. I think Wiki needs "life sized examples" to balance the simplicity of short ones though. The "instructions" in RefactoringWikiPages are helpful, including your latest updates, because they're concise. The volume of instructions and the fact they don't anything like cover so many issues raised in my own experience fills me though with two pressing questions:

"how can LessIsMore apply since Wiki stopped relying simply on GoodStyle?"
"how can we do examples properly without compounding the problem?"

I know that I don't know how. -- RichardDrake

CategoryWikiRefactoring