[development] Reviewing patches and making decisions -> Sociocracy could be a way to go!

[David Metzler]

Funny that I was having just this discussion with my Dev team at work  
today.  How shall we document how/why something works.   I think most  
of the folks agreed that closer to the code is better. So comments is  
the best answer but it's often difficult to document how disparate  
modules connect in code comments.

Another resource that we have that's not used as much as it could be  
is the API module and it's document generation techniques.  It  
already documents much of the bigger picture with core modules.   
Correct me if I'm wrong, but cannot developers maintain "extra"  
technical documentation in a separate document along with their  
modules in CVS?  That might be a good thing to version control, but  
keep a static document, that feeds api documentation. I know this is  
possible with other modules such as Doxygen, but am not sure that it  
works in API module. (but I bet it could). This is the solution we  
landed on in my dev shop.

That way rational/design info could(should?) be supplied with  
patches.  In separate documentation and it would help those who do  
patch review understand how/why something is supposed to work before  
it gets committed.

You see that's the one problem with using CVS annotate.  The commiter  
provides that message, but the patch submitter is the one who needs  
to supply the documentation :).  And remember our goal here is to  
make it easier for the review/commit phase, so adding doc work to the  
commiter is counter productive.

So I like using CVS for why something changed, but not how something  
is supposed to work.  That needs to be in code comments or lean text  
base documentation that goes with the code.

But perhaps we near exhausting all that can be said on this issue.

On Nov 6, 2008, at 8:21 PM, Angela Byron wrote:

> On 11/6/08 6:19 AM, Thomas Zahreddin wrote:
>> Hi Angie,
>>
>> thank you for answering the first third of my mail. I think we are  
>> not on the
>> same page:
>>
>> in the last third I wrote explicit, that I know all the tools and  
>> places where
>> to find informations - but i also mention that it is impossible to  
>> follow all
>> relevant information.
>>
>> To lower the workload for us all we need a summery on a much  
>> higher level than
>> CVS-messages (btw how many do we count a day - my estimation is  
>> two a minute).
>
> I answered the first third, because it seemed to me that the last  
> two thirds were based on the presumption that the information you  
> seek is not readily available. But CVS annotate seems to do exactly  
> what you request and it requires no manual effort on the part of  
> our already over-burdened maintainers to keep up to date, since  
> it's updated automatically with every commit.
>
> In what specific ways does CVS annotate not get you what you're  
> asking for? That would probably help the justification for your  
> proposal be a bit more clear.
>
> -Angie