>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 ?
>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 ?
>On the other hand, a separate docs repository has one
>potential advantage
>as well: we can grant CVS commit privileges on the docs to
>people who do
>not have those privileges on the code repositories. To me,
>this isn't a
>big deal -- if we can trust people to get the docs right, we should be
>able to trust them not to screw up the code -- but it's still there.
That's the goal. a redactor will have access only to J-T-D. A tomcat
commiter will have access to code & docs...
>> > * The files that are checked in should only be the XML
>sources, *not* the
>> > generated files. This varies from what Jon set up in
>jakarta-site2,
>> > based on long and drawn out earlier discussions (same
>issues as those
>> > surrounding checking JAR files into CVS :-).
>>
>> Someone will have to setup something that exposes the latest
>generated
>> documentation on the Jakarta www site. It's being done
>already for Struts,
>> so I guess that won't be a big problem.
>>
>
>It's pretty straightforward.
>
>> > * At least two documentation webapps (developer-oriented and
>> > user-oriented) would seem to be appropriate. Having
>more than two
>>
>> "developer" as in "web" or "Tomcat"? I'm not sure why
>separating the doc
>> into two packages helps - perhaps I'm missing some obvious
>benefit trying to
>> think at 7:15am =)
>>
>
>"Developer" in the sense of this sentence is a Tomcat
>developer. "User" is the people that just want to download, install,
>configure, and utilize Tomcat as a servlet container.
And a third category is the redactor, someone who write docs to explains
users how to install and run TC stuff. He also describe to potentials
new developpers Tomcats (3.2/3.3/4.0) architectures and how they could add
functionnalities to the main core. That's why Apache HTTPD server was
so successfull...
