tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GOMEZ Henri <>
Subject RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatD ocumentation Redactors To Hire]
Date Tue, 10 Jul 2001 07:27:04 GMT
>> 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 
>> >   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 
>> 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...

View raw message