storing particular release documentation in SVN in our project web-site pages

[Marshall Schor <ms...@schor.com>]

Currently, our uima-website project stores a copy of each release's 
documentation.  This can be quite large, mainly due to the Javadoc API storage 
which is around 20 MB. A previous discussion pointed out that this was probably 
not an issue for SVN, which was cited as being good for storing lots of small 
things.

This was contrasted to an alternative, where we might use the official 
distribution site to store not only our zipped/tarred up releases, but also 
copies of the documentation;  it was pointed out that the mirroring mechanism 
was "tuned" to work with fewer numbers of large files, as opposed to lots and 
lots of little ones (which is the organization of the Javadoc html site). 
Because of this we were advised against putting our Javadocs, especially, on the 
mirroring distribution site, in expanded form for access from our web-site.

The website for UIMA on people.apache.org is built doing an SVN update.  Only 
the docs/ directory is checked out.

The current situation is that we have in SVN copies of the docs (Javadocs, plus 
docbook docs in html and pdf format) for all releases (of UIMA).  < Well, that's 
not quite accurate - some of the previous releases didn't have all the docs put 
up on the web site apparently >.  But we only provide links on our website to 
the "current" release of the Javadocs, even though we have the older releases 
available.

This seems inconsistent; we should either have pointers to all the docs for all 
the releases, or, if we decide not to provide links to other than the current 
release, we should not burden the website with storing the older releases (even 
though the storage of these in SVN cannot be reclaimed).

If we continue to store copies of the expanded release docs as entities in our 
SVN in the web-site project so we can have them available on the web site, I 
would prefer that we change the website to have links to all the documentation 
for all the releases that is available in SVN.  These could be categorized to 
reduce clutter.  Other opinions?

-Marshall

Re: storing particular release documentation in SVN in our project web-site pages

[Tong Fin <to...@gmail.com>]

Let's look at this from the user's perspective.  Who of our users
> needs access to all the old documentation?

+1 I agree. I only has a link and access to "current" document.

If there is a significant
> number of people who would benefit from this, then I'm for it.

If I need the "old" documents, I will download that old released package !

Instead of the old versions, I have more interested on the BETA version to
know what new APIs are coming and what old APIs will be gone or depreciated.
I don't think we have this BETA section (yet ?).

- Tong

Re: storing particular release documentation in SVN in our project web-site pages

[Marshall Schor <ms...@schor.com>]

Thilo Goetz wrote:
> Adam Lally wrote:
>> On Fri, Jul 25, 2008 at 10:07 AM, Thilo Goetz <tw...@gmx.de> wrote:
>>> So you're saying having the old documentation is marginally
>>> useful.  Then I suggest we create an "archive" section where
>>> we put all the old stuff, distributions and documentation.
>>> Less clutter, but it's still around.
>>>
>>> Currently we have the old documentation higher up on the screen
>>> than the "getting started" guides.  The old stuff should go where
>>> it's not obsuring current information.
>>>
>>
>> +1.  I agree the old documentation shouldn't be where it gets in the way.
>>
>> We should just make sure that the URLs don't change when things are
>> moved to the archive section, so that links to break.  So the file
>> structure should still be organized by release, but we can redesign
>> the main Documentation page to make the current docs much more
>> prominent.
>>
>>   -Adam
> 
> Sounds good to me.  It should be no problem to keep the links
> constant, I agree that's a requirement.

+1 -Marshall

> 
> --Thilo
> 
> 
> 

Re: storing particular release documentation in SVN in our project web-site pages

[Thilo Goetz <tw...@gmx.de>]

Adam Lally wrote:
> On Fri, Jul 25, 2008 at 10:07 AM, Thilo Goetz <tw...@gmx.de> wrote:
>> So you're saying having the old documentation is marginally
>> useful.  Then I suggest we create an "archive" section where
>> we put all the old stuff, distributions and documentation.
>> Less clutter, but it's still around.
>>
>> Currently we have the old documentation higher up on the screen
>> than the "getting started" guides.  The old stuff should go where
>> it's not obsuring current information.
>>
> 
> +1.  I agree the old documentation shouldn't be where it gets in the way.
> 
> We should just make sure that the URLs don't change when things are
> moved to the archive section, so that links to break.  So the file
> structure should still be organized by release, but we can redesign
> the main Documentation page to make the current docs much more
> prominent.
> 
>   -Adam

Sounds good to me.  It should be no problem to keep the links
constant, I agree that's a requirement.

--Thilo

Re: storing particular release documentation in SVN in our project web-site pages

[Adam Lally <al...@alum.rpi.edu>]

On Fri, Jul 25, 2008 at 10:07 AM, Thilo Goetz <tw...@gmx.de> wrote:
> So you're saying having the old documentation is marginally
> useful.  Then I suggest we create an "archive" section where
> we put all the old stuff, distributions and documentation.
> Less clutter, but it's still around.
>
> Currently we have the old documentation higher up on the screen
> than the "getting started" guides.  The old stuff should go where
> it's not obsuring current information.
>

+1.  I agree the old documentation shouldn't be where it gets in the way.

We should just make sure that the URLs don't change when things are
moved to the archive section, so that links to break.  So the file
structure should still be organized by release, but we can redesign
the main Documentation page to make the current docs much more
prominent.

  -Adam

Re: storing particular release documentation in SVN in our project web-site pages

[Thilo Goetz <tw...@gmx.de>]

Adam Lally wrote:
> On Fri, Jul 25, 2008 at 3:09 AM, Thilo Goetz <tw...@gmx.de> wrote:
>> Let's look at this from the user's perspective.  Who of our users
>> needs access to all the old documentation?  If there is a significant
>> number of people who would benefit from this, then I'm for it.  Else,
>> let's not put up information that nobody needs.
>>
> 
> Well, what is the usefulness of having all the documentation online
> anyway, even for the current version?  People who just want to learn a
> little about UIMA without downloading it don't need our entire
> documentation.  Those who are working with UIMA closely enough to
> need, say, the reference guides, won't have a problem looking it up in
> the download package.

I use the online version all the time, but maybe I'm just weird
that way.

> 
> I can think of a couple reasons why online documentation is useful:
> 
> 1) If someone asks a question on the mailing list, it is convenient to
> paste a link to the online HTML version of the docs that answers it.
> Before we had this it was always a pain to refer to sections of the
> manual because the section numbers may change from the current manual
> vs. the one the user has downloaded.
> 
> 2) For the javadocs, you can link to them from other javadocs (for
> something that has embedded UIMA).
> 
> 
> When you are providing links to the docs, it can be useful to have
> previous versions around so that the links don't break.  For #1, if a
> user has identified what UIMA version they use when they ask the
> question, you can provide a link to that version of the docs.  This is
> only marginally useful, I have to admit, because the chances are low
> that (a) a user bothered to actually tell you what UIMA version they
> have :) and (b) the particular section in question happened to have a
> relevant change.  For #2 I think it is actually more important, since
> individual APIs certainly do change, and the linked javadocs will no
> longer represent what's really going on in the version that is
> embedded in the user's application.
> 
>  -Adam

So you're saying having the old documentation is marginally
useful.  Then I suggest we create an "archive" section where
we put all the old stuff, distributions and documentation.
Less clutter, but it's still around.

Currently we have the old documentation higher up on the screen
than the "getting started" guides.  The old stuff should go where
it's not obsuring current information.

--Thilo

Re: storing particular release documentation in SVN in our project web-site pages

[Adam Lally <al...@alum.rpi.edu>]

On Fri, Jul 25, 2008 at 3:09 AM, Thilo Goetz <tw...@gmx.de> wrote:
> Let's look at this from the user's perspective.  Who of our users
> needs access to all the old documentation?  If there is a significant
> number of people who would benefit from this, then I'm for it.  Else,
> let's not put up information that nobody needs.
>

Well, what is the usefulness of having all the documentation online
anyway, even for the current version?  People who just want to learn a
little about UIMA without downloading it don't need our entire
documentation.  Those who are working with UIMA closely enough to
need, say, the reference guides, won't have a problem looking it up in
the download package.

I can think of a couple reasons why online documentation is useful:

1) If someone asks a question on the mailing list, it is convenient to
paste a link to the online HTML version of the docs that answers it.
Before we had this it was always a pain to refer to sections of the
manual because the section numbers may change from the current manual
vs. the one the user has downloaded.

2) For the javadocs, you can link to them from other javadocs (for
something that has embedded UIMA).


When you are providing links to the docs, it can be useful to have
previous versions around so that the links don't break.  For #1, if a
user has identified what UIMA version they use when they ask the
question, you can provide a link to that version of the docs.  This is
only marginally useful, I have to admit, because the chances are low
that (a) a user bothered to actually tell you what UIMA version they
have :) and (b) the particular section in question happened to have a
relevant change.  For #2 I think it is actually more important, since
individual APIs certainly do change, and the linked javadocs will no
longer represent what's really going on in the version that is
embedded in the user's application.

 -Adam

Re: storing particular release documentation in SVN in our project web-site pages

[Thilo Goetz <tw...@gmx.de>]

Adam Lally wrote:
> On Thu, Jul 24, 2008 at 4:40 PM, Marshall Schor <ms...@schor.com> wrote:
>> The current situation is that we have in SVN copies of the docs (Javadocs,
>> plus docbook docs in html and pdf format) for all releases (of UIMA).  <
>> Well, that's not quite accurate - some of the previous releases didn't have
>> all the docs put up on the web site apparently >.  But we only provide links
>> on our website to the "current" release of the Javadocs, even though we have
>> the older releases available.
>>
>> This seems inconsistent; we should either have pointers to all the docs for
>> all the releases, or, if we decide not to provide links to other than the
>> current release, we should not burden the website with storing the older
>> releases (even though the storage of these in SVN cannot be reclaimed).
>>
> 
> I agree it doesn't make much sense the way it is now.
> 
>> If we continue to store copies of the expanded release docs as entities in
>> our SVN in the web-site project so we can have them available on the web
>> site, I would prefer that we change the website to have links to all the
>> documentation for all the releases that is available in SVN.  These could be
>> categorized to reduce clutter.  Other opinions?
>>
> 
> That seems okay to me.  I don't have a strong feeling either way.
> 
>  -Adam

Let's look at this from the user's perspective.  Who of our users
needs access to all the old documentation?  If there is a significant
number of people who would benefit from this, then I'm for it.  Else,
let's not put up information that nobody needs.

--Thilo

Re: storing particular release documentation in SVN in our project web-site pages

[Adam Lally <al...@alum.rpi.edu>]

On Thu, Jul 24, 2008 at 4:40 PM, Marshall Schor <ms...@schor.com> wrote:
> The current situation is that we have in SVN copies of the docs (Javadocs,
> plus docbook docs in html and pdf format) for all releases (of UIMA).  <
> Well, that's not quite accurate - some of the previous releases didn't have
> all the docs put up on the web site apparently >.  But we only provide links
> on our website to the "current" release of the Javadocs, even though we have
> the older releases available.
>
> This seems inconsistent; we should either have pointers to all the docs for
> all the releases, or, if we decide not to provide links to other than the
> current release, we should not burden the website with storing the older
> releases (even though the storage of these in SVN cannot be reclaimed).
>

I agree it doesn't make much sense the way it is now.

> If we continue to store copies of the expanded release docs as entities in
> our SVN in the web-site project so we can have them available on the web
> site, I would prefer that we change the website to have links to all the
> documentation for all the releases that is available in SVN.  These could be
> categorized to reduce clutter.  Other opinions?
>

That seems okay to me.  I don't have a strong feeling either way.

 -Adam