Re: 3D: Documentation Driven Development

whit wrote:

> 1. the people I am concerned with informing or being involved are active 
> on this list.  maybe it's because personally the habit of following this 
> list is more ingrained than reading at's product area, but PSC doesn't 
> personally figure into where I participate in developing AT.

No, I totally agree that discussions should happen on the list, but 
rather than put the end result in a text file in svn, I'd suggest we use 
the tools available to manage improvement proposals. I'm sure the 
release manager would find it easier to work with a tool that let him 
get a good overview over what proposals were in what states of progress 
(discussed, in progress, ready to be merged etc.) and what releases 
they'd been intended for, if nothing else.

> 2. What we are talking about is fundemental refactoring of low level 
> code, not a high level description of a feature.

Sure, but that text could still go on plone.org rather than 
svn.plone.org, no?

> 3. Maintaining this list and links in this list is a manageable vector 
> of information (it's the minimal amount I can do and be effectively 
> communicating).  A proposal in PSC and in a doctest is duplication of 
> effort.

Aha - you mean *doctest*. Interesting...

> 4. The tests will live in svn, not PSC, so as documentation grows 
> executable code, it makes more sense for it to be in the tool chain, 
> rather than growing stale in the website.
> 
> 
> 5. the intention is that the end result is not a staling proposal left 
> to confuse googlers of the future but an executable test proving that 
> the proposal works(or doesn't). Again, this is maybe more important for 
> infrastructure...
> 
> 
> this is an experiment, and it's not exactly the way we do it now. I'm 
> fine doing my thing my way, but I thought I'd share the logic, since it 
> seems compelling to me.

I quite like the idea of proposals being executable tests, in fact. I 
wonder whether perhaps we could manage some of the meta-data and 
high-level overview in the PSC still; just more general points about the 
rationale, the problem and so on, so that we had a bit more visibility 
of what's going on and what state it's in. The list is great for things 
being dicussed right now, but less good for piecing together the state 
of discussion and progress (which may be hard to glean from hard code or 
even tests, too, unless you're careful) a few months down the line.

Note the a PSC proposal can link to an svn branch where development 
happens, so if the text there is fairly short (and at a high enough 
level for regular people to figure out what's going on, in general) it 
can defer to the text for all specifics.

Put it differently: I find the text of your doctest at the moment a bit 
confusing for getting the bigger picture, and I'm sure I'm not the only 
one. Also, with *just* a doctest in svn, we'd have to manage the process 
of what proposals are intended for what releases and what state they're 
in by memory and emails back and forth. These are the problems the 
PSC/PLIP infrastructure solve for Plone and tons of other products. I 
think they're orthogonal to describing low-level changes in terms of a 
doctest, though (which I think it's a bloody great idea).

Martin



-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642