Forum OpenACS Development: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS

13: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 12)

Posted by Tilmann Singer on 01/15/03 10:19 AM

I cannot imagine that this well known methodology advocates leaving a developer who needs to work with existing software written by someone else totally clueless about the purpose of that software. I think the typical 'Big Picture' paragraph at least is essential for every OpenACS package - why should other developers waste hours finding out what the original author could provide in a few minutes? But propably we agree on this anyway, it's just not really clear to me from the previous comments.

14: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 13)

Posted by Simon at TCB on 01/15/03 11:08 AM

We do agree. I'm referring to technical desing documents. whihc at best shuld be minimal if at all. A design document is useful *prior* to implementation, but not afterward.

At least in this kind of project. I'm sure building software for missle guidance systems or airline operation requies a different approach, but thats hardly relevant here ;o)

Besides, reading code is actually quicker (and weill certainly be a true system description).

Ok, I'll accept that in an ideal world, with infinite resources that can work at the speed of light, then having perfectly matched documents is good.

But as thats not the case, whats the point of aimn at the unattainable, better to work with human nature and circumstance?