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

Collapse
12: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS (response to 11)
Posted by Simon at TCB on 01/15/03 09:43 AM
Andrew,

Despite you feverent language, its not actually utter nonsense. In actual fact it forms part of the basis of a well know (and widely implemented) development methodology.

And, if I could just refer you to my earlier post in its entirety I think I did point out this applies only to techncal docs, not user guides/overviews etc.. i.e. one may as well, in projects like this, avoid the lenghy design docs that server little purpose after the code is released.

But thanks for misrepresenting what I said :o) How good  it is to be be back ...

Collapse
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.
Collapse
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?