The project has gotten to the stage where we are starting a slow rollout of this codebase, and now documentation is the focus. The problem is, I've got all of this new code that uses some OOP-fu to clean up some long-standing issues, and there's no clear way to document the little beast. It's the Inside Macintosh problem all over again!
Feels like it's time for a little more refactoring. Time to clean up the new code so that it does the same thing, but is easier to document and extend. That'll make my immediate job easier, but also make it easier for new developers to adopt.
Why more refactoring now? Because refactoring is like an oil change for your car. The longer you delay, the worse it gets, and the more damage it does. Delay long enough, and everything seizes up, which leaves you two options: major remediation, or a total replacement. Refactoring (or regularly changing the oil), is a minor cost to pay for ongoing high performance.
The XP folks say that a day without refactoring is like a day without sunshine. That's a pretty extreme view to take when dealing with management that treats refactoring as expensive retrograde work producing no net value. (Fortunately, I'm not in that position. Now.) Maybe the answer is the 10% solution: can you afford to spend one day every other week to make your code suck less? Not fix every problem, but just make it suck less?
 The original edition of Inside Macintosh (later known as Inside Macintosh, Volume I) was a reference book of 25 chapters, each written with the expectation that you had read and fully understood the other 24 chapters it built on.