Robert Burrell Donkin wrote:
> (apologies for not jumping in promptly)
>
> On Dec 24, 2007 3:48 AM, Marshall Schor <msa@schor.com> wrote:
>   
>> I updated our website download page and documentation page.  I made the
>> download page work with mirrors, and changed the format for accessing
>> previous archived files to follow the common practice on other sites,
>> referring to the archive.apache.org site.
>>
>> I made our documentation page refer to apache.org/dist/incubator/uima
>> for the doc files - and didn't put any of these into our SVN for our
>> website.
>>     
>
> after feeling a little uncertain about this, i asked the
> intrastructure team who gave some good arguments for storing docs in
> dist:
>
> 1. rsync is good for large files but struggles with lots of small files
> 2. mirrored documentation is not supported so push all that content to
> the mirrors is wasteful
> 3. released documentation should have an unchanging URL. when a
> release is archived, the documentation URL would need to change (a
> redirect would help people but not all robots).
>
> having release documentation permanently stored and archived is a good
> idea but it's strongly recommended that subversion is used. the zip'd
> archive is fine where it is but it would be better for the contents of
> the folders to be committed to subversion and then checked out to an
> appropriate place on the website.
>
> - robert
>   
I felt uncertain about all of this, too.  It seems to me that the right
way to do this would be to have something like w.a.o/dist-not-mirrored/
... etc. where the same "archive" mechanism could be used as is used for
/dist/, but which doesn't do mirroring.  Has this come up before in
discussions - a way to have things that are not to be mirrored, but 
which would reasonably be "archived"?  You might say that the docs don't
need to be archived (because they can always be extracted from an
archived "release" zip/tar), but I find having at least some older
versions of the docs quite useful in helping users running on a specific
level - I can say things like "see xxx on page yyy" and know it matches
their documentation.  

It seems inefficient to store large generated things in SVN, such as the
javadocs (these are large numbers of small files) -- but I would be
happy to learn if I'm worrying about this unnecessarily.

I can see an argument against something like w.a.o/dist-not-mirrored/ -
avoiding creating even more "infrastructure stuff". 

Other opinions / options? 

-Marshall