[Twisted-Python] Re: Status of 1.1 release

[Glyph Lefkowitz]

Donovan Preston wrote:

> Documenting [form] would mean semi-freezing the interface, and since the 
> interface is just slush and has already changed (in quotient.formless 
> and quotient.web.webform), I don't think it's a great idea. One thing 
> people need to understand about woven is that it is still in heavy 
> development -- although development has slowed lately because it has 
> become stable enough to use, there are still large refactorings I plan 
> on undertaking which will vastly simplify the way woven works. While I 
> will attempt to preserve backwards compatibility because I have a large 
> codebase that needs it, I reserve the right to change interfaces because 
> they are completely broken -- I think it'll be better in the long run to 
> have well-designed interfaces than to have backwards compatibility with 
> broken ones.
> 
> The best way to learn about woven is to try to use it, and to ask 
> questions on #twisted.

I have added some notes to other aspects of the Twisted documentation to 
try to bridge this communication gap.  Any document where the thing 
being documented is under heavy development should clearly and loudly 
say that.

I mention this because I agree with Donovan's point here, but sometimes 
writing documentation for code can be as enlightening a process as 
writing test-cases for it; possibly revealing ways to produce 
backwards-compatible refactorings without endangering correctness.  I 
don't want to discourage anyone from doing that.  If you do it, though, 
understand that you may have to maintain the document forward to a new 
interface when it changes.