Re: 3D: Documentation Driven Development

Martin Aspeli wrote:
> whit wrote:
>> I've been looking at how the 'py' project organizes themselve using 
>> documentation driven development.  Sort of goes like this:
>>
>> 1. write documentation for a feature
>> 2. write tests for the documentation
>> 3. write code to make the tests pass
>> 4. refactor 1, 2, and 3 as need
>> 5. rinse and repeat
>>
>> how would people feel about creating a proprosals directory in the AT 
>> repository to start doing something like this.  I'll create it and stick 
>> this proposal in. we can edit it as we see fit, finished product being 
>> something we can literally write the implementation against?
> 
> Mmm... could we not rather just use 
> http://plone.org/products/archetypes/roadmap, which is a bit more 
> accessible to people without a deep knowledge of svn (which may in fact 
> include capable developers who just don't contribute, or people who are 
> just interested in our architecture).
> The PSC also gives us some tools to better develop comment on and manage 
> proposals in relation to releases - and it gives us some consistency 
> with what Plone itself uses.

let me break down the reasoning.

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.


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


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.


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.


-w






  | david "whit" morriss
  |
  | contact :: http://public.xdi.org/=whit

  "If you don't know where you are,
   you don't know anything at all"

   Dr. Edgar Spencer, Ph.D., 1995


  "I like to write code like
  other ppl like to tune their
  cars or 10kW hifi equipment..."

  Christian Heimes, 2004



-------------------------------------------------------------------------
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