[development] Reviewing patches and making decisions -> Sociocracy could be a way to go!
metzlerd at metzlerd.com
Fri Nov 7 05:28:13 UTC 2008
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.
More information about the development