DocumentRefactoring

Last edit March 14, 2013

Modern practices in TechnicalWriting and the ForthLanguage both suggest refactoring large procedures -- and for the same reason, that refactored procedures are easier to read.

Does Forth let you write procedures so large as to need refactoring? The last time I played with Forth "pages" were limited to 1K IIRC

Traditional Forth implementations use "blocks" for source code. A "block" is 1K, usually arranged into 16 lines of 64 characters each. However, a "word" requiring a whole block for its definition would be huge by Forth standards. The Forth community placed early emphasis on "factoring" code to improve readiblity and save storage. LeoBrodie's ThinkingForth includes extensive discussion of code factoring. --

When to refactor? It's probably not worth bothering unless you have to scroll the page to see it all. Once a page grows where you can't see it all at once, then it might be time to look for obvious subtopics and themes.

See the ExtremeProgramming page for an example -- it has spawned several subtopics. (But it's still big.)

I've recently started an experiment at home, using Wiki to write a manual. While I've only spent a few hours at it, I've learned a few things already:

Imposing a structure (outline) on an organic framework (Wiki) does work. If you're writing a manual. We aren't. Sure, but others of us are trying to use Wiki as a real-world tool. So we (well, Larry and I) are. Writing manuals, that is.
A good outline makes it easy to refactor a section.
Balance your time between writing and adjusting the outline (i.e. refactoring) to keep things under control.
Take advantage of BackLinks. Add a few of your own in the deeper pages.

Now, to write a WikiToTroff script.... -- LarryKollar

Found it again...I was looking for the paragraph at the top of this page and it had been refactored out :o)

Not much of a refactoring, then, was it? And it probably took you a while to realise that something had been dropped. Face it, Wiki pages can't be refactored in the sense that the term is used in the XP, and other, technical communities.

 - but what I really want to ask is -

where did this come from? I'd be interested to read about Modern practices in TechnicalWriting, could whoever wrote the line at the top of this page suggest some background reading (web pages preferred, though I still like books)?

On Modern practices in TechnicalWriting -> Actually, it's just the same as in software (DRY, Modularization, Minimize the Interface). However, TW is something like 20 years behind the software industry, "IDE for Documentation" has been around only for less than 10 years. DRY goes on topic level, paragraph, even on word level (same things have same names) - because most translators charge you cents-per-word. If you enforce strict rules and refactor every now and then, costs for content creation and translation go down significantly. (Martin Brueggemann)

Refactoring in Wiki is definitely different than refactoring code, though the analogy is a useful one. When I first started using Wiki, I thought that the fact that Wiki 'lacks unit tests' would make refactoring less useful. Now I believe that it only makes it harder, not less useful. Our closest thing to unit tests is PeerReview, mostly via RecentChanges.

Regardless, Wiki is far too exploratory to benefit from an imposed structure (as suggested by WhyBotherToStructure). If you're writing your own Wiki, different heuristics may apply, but this Wiki's strength comes from its emergent structure which is accomplished by DocumentRefactoring, RoadMaps, catergories, etc. -- RobHarwood

One way to implement a sort of unit-test would be to ValidateChangesByVoting. -- MichaelRoss

I've been using Twiki to directly create a "suggested reading order" that can be printed. See http://twiki.org/cgi-bin/view/Codev/TocAndReportGeneration for additional information -- StanleyKnutson