Michael Baessler wrote: > Marshall Schor wrote: >> Michael Baessler wrote: >> >>> Robert Burrell Donkin wrote: >>> >>>> subversion really is the way to go for release documentation >>>> >>> OK, so as far as I understand we go with the documentation the same >>> way as with the previous Apache UIMA releases. We check in the >>> documentation >>> to SVN and provide a download similar to release 2.2.0-incubating: >>> >>> http://incubator.apache.org/uima/downloads/releaseDocs/2.2.0-incubating/docs/html/index.html >>> >>> >>> >>> The JavaDocs will also go to SVN in both versions, HTML and zip. >>> >>> I can do the necessary changes, if all agree on that. >>> >>> -- Michael >>> >>> >>> >>> >> +1. >> >> Also - remove the docs from /dist/incubator/uima >> >> -Marshall >> > Should we really remove the documentation from there. I think other > projects also have the documentation there. So I think we should > provide it too, maybe as one package to download.? > > -- Michael This one is a judgement call - I can see arguments on both sides.
We've heard that the "rsync" mechanism handles small numbers of large files better than large numbers of small files - so putting only the 1 archive file to download seems a better fit, if we do this. Putting them in /dist/ means they will be mirrored, and archived. So we will have dual archiving (one in SVN, and one in the archive spot). The mirroring would be useful *if* we expected a large load on the apache servers for downloading these. I think this will not be the case. Most of the time I use these to send people links to specific sections of the docs; for that it would be annoying if when they clicked the link, they were asked to pick a mirror. Considering all of this - I'm slightly in favor of keeping the docs just in SVN, and not on the /dist/ mirroring system. ------------ Some more things to think about ------------ Since we want our docs pages to refer not only to the "current release" but also previous releases, it would be good to figure out a fairly automatic system for this. (That was a virtue of the /dist/ - archive system - we could point the previous releases doc links to a directory containing all the releases, and wouldn't need to update this link for subsequent releases). The other thing to do is to figure out how to keep the archived things on our web-site. It was suggested that we should do this like we handle the web-site checkout. Probably the straight-forward thing to do is to have a special directory where all the docs we want to refer to live, have the archive link point there, and have special links that refer to the "current version". As I recall, the web-site, itself, is replicated to other servers (since after you update it , you have to wait a while for it to appear). I have to confess that this seems quite wasteful of disk resources (double+ copies of things like javadocs - one in SVN, one on people.apache.org in our web-site place, and maybe (several?) additional copies on web-servers used for incubator.apache.org/uima). But Robert Donkin suggested this was the best way. -Marshall
