On Tue, 10 Jul 2001, GOMEZ Henri wrote:
> >Craog
> >> I have a feeling that whatever is the same will be a lot of
> >piecemeal here
> >> and there, excluding of course, web-app documentation. So
> >far yourself,
> >> Pier, and Henri are the only three TC developers to post
> >their position on
> >> that (re: inter-version relevancy).
>
> Pier and I also working together on a separate sub-project, J-T-C.
> A starting user will first install the servlet-engine and then will
> try to figure how to link it with its web-server.
> Should we ask him to switch from one documentation to another ?
>
The user doesn't care what repository the docs came from -- they only care
that the hyperlinks work correctly :-).
In other words, the packaging of the docs in the binary distribution need
not have anything to do with the source file organization.
> >I thought of another reason for my preference in the shower
> >this morning
> >:-). Consider that I might make a code change that also
> >requires a change
> >to the corresponding docs. If the docs are in the same
> >repository, that
> >can easily be done on the same commit (and it becomes obvious
> >to everyone
> >when a developer makes a change that breaks the documentation,
> >but fails
> >to update it :-). Having a separate docs repository means I need to do
> >two independent check-ins -- it's easy to forget one, and there is no
> >obvious link between them to remind you (for example) to back
> >out the docs
> >change if you back out the code change.
>
> If you commit a code change in TC 4.0, you'll only have one doc commit
> in J-T-D. What's the duplicate effort here ?
>
Assume a change to class Abc.java and a corresponding change to
Abc-doc.html.
If they are in the same CVS repository, a single commit does
both. Otherwise, you need to remember to do two individual commits (one
on each repository).
Likewise, when you decide later to back out this change (because it was
incorrect or something), you have to remember that there was also a commit
on the docs repository. In the same repository, the commit message
contains both sets of changes, so you know that you have to back them both
out.
Craig McClanahan
