[ServerEntry] Comments

[Emmanuel Lecharny <el...@gmail.com>]

Hi Alex, and guys,

I have added some comments on the ServerEntry page :
http://cwiki.apache.org/confluence/display/DIRxPMGT/ServerAttribute+code?focusedCommentId=68138#comment-68138
and
http://cwiki.apache.org/confluence/display/DIRxPMGT/ServerAttribute+code?focusedCommentId=68531#comment-68531

I think it's better to add comment this way than modifying the code on
svn, if they are general comments. For code comments, or modification,
the best would be to do it directly on code, and commit the code.

-- 
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com

Re: [ServerEntry] Comments

[Emmanuel Lecharny <el...@gmail.com>]

On 10/11/07, Alex Karasulu <ak...@apache.org> wrote:
> Hi Emmanuel,
>
> This duplicates data in both confluence and in SVN.
>
> Confluence is bulky.  Why bulk it up more with versioning code in flux with
> it. Subversion
> does this better.

I agree. However, I like to push the first drop in confluence, because
I don't mess the branch. But as soon as the code (and tests) are in
subversion, I think that nothing could compare to code and javadoc. I
will clean confluence from all those garbages.

> What about this instead?
>
> (1) comment code in the code and discuss things on the mailing list

We just need to add some very clear comment when we commit the code.
We are smart enough to read the diffs, so it should be perfectly ok.

> (2) stabilize interfaces after several passes then commit to them

We can commit until we get something clear and agreed.

> (3) remove the code from confluence and just reference the code in
> subversion

Yes, and we can also simply remove all references, because JavaDoc
should be enough ( we still have to generate javadoc for the project
btw :)

> (4) remove @todo comments talking about design issues and use them to
>      compose the design documentation explaining these choices made
> (5) use extra energy and time to organize better the developer documentation
>      on this and give synopsis using our new Posidon tool to show a clear
> picture

YES YES YES !

>
> If you really want to duplicate this code in confluence then I'll do that
> our of courtesy.
> However I'm hoping you think twice about it and save me the trouble.

Nope, As I said, I like to do thing first in confluence because it
helps me to organize my thoughts. I would say it forces me to clarify
what I have in mind. Everybody his own method, and I wont force you to
do so.


> P.S.
> I have been noticing that the quality of the developer documentation is
> dropping because
>  we use it as a scratch pad which is fine but we never really cleanup.  Or
> we mix the essential
> concepts in with lots of irrelevant notes.  So this bypasses the purpose of
> transferring knowledge
> quickly and efficiently to our team.

I hope you are not talking about the ServerEntry stuff :)

-- 
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com

Re: [ServerEntry] Comments

[Alex Karasulu <ak...@apache.org>]

Opps ...

On 10/11/07, Alex Karasulu <ak...@apache.org> wrote:
>
> (4) remove @todo comments talking about design issues and use them to
>      compose the design documentation explaining these choices made


To clarify I mean real design documentation in confluence.

(5) use extra energy and time to organize better the developer documentation
>
>      on this and give synopsis using our new Posidon tool to show a clear
> picture
>

Again this is in confluence.

Alex

Re: [ServerEntry] Comments

[Alex Karasulu <ak...@apache.org>]

Hi Emmanuel,

This duplicates data in both confluence and in SVN.

Confluence is bulky.  Why bulk it up more with versioning code in flux with
it. Subversion
does this better.

As we bounce around ideas in this volatile stage we may make several
changes.  And
for each change we have to maintain it in two places.  Furthermore there's
going to be
a perpetual synchronization problem.

What about this instead?

(1) comment code in the code and discuss things on the mailing list
(2) stabilize interfaces after several passes then commit to them
(3) remove the code from confluence and just reference the code in
subversion
(4) remove @todo comments talking about design issues and use them to
     compose the design documentation explaining these choices made
(5) use extra energy and time to organize better the developer documentation

     on this and give synopsis using our new Posidon tool to show a clear
picture

If you really want to duplicate this code in confluence then I'll do that
our of courtesy.
However I'm hoping you think twice about it and save me the trouble.

Also if our developer documentation is riddled with scratch pad notes and
contains
code duplicated in the repository but out of sync who's going to want to
deal with
filtering that volume of information.  On this track we're going to make the
developer
documentation ineffective.

Thanks,
Alex

P.S.
I have been noticing that the quality of the developer documentation is
dropping because
we use it as a scratch pad which is fine but we never really cleanup.  Or we
mix the essential
concepts in with lots of irrelevant notes.  So this bypasses the purpose of
transferring knowledge
quickly and efficiently to our team.

On 10/11/07, Emmanuel Lecharny <el...@gmail.com> wrote:
>
> Hi Alex, and guys,
>
> I have added some comments on the ServerEntry page :
>
> http://cwiki.apache.org/confluence/display/DIRxPMGT/ServerAttribute+code?focusedCommentId=68138#comment-68138
> and
>
> http://cwiki.apache.org/confluence/display/DIRxPMGT/ServerAttribute+code?focusedCommentId=68531#comment-68531
>
> I think it's better to add comment this way than modifying the code on
> svn, if they are general comments. For code comments, or modification,
> the best would be to do it directly on code, and commit the code.
>
> --
> Regards,
> Cordialement,
> Emmanuel Lécharny
> www.iktek.com
>