You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by "Tim Colson (tcolson)" <tc...@cisco.com> on 2005/02/17 17:28:44 UTC

RE: generated docs in repo

 
> > Which brings me back to the question:  Do we really want
> > *auto-generated* documents in the repo?
> 
> for the record, i've been told that this was done to make updating the
> site "easier".  rather than uploading the generated docs to the site
> directly, we check them in to the repo and just do a cvs (or svn)
> update of them at the web site's root.  but personally, i've never
> been convinced that this is that much easier.

I'm in the same boat as Shinobu... seems anything that can be generated
doesn't belong in the repo. But based on Nathans info, I can understand
reasons* why it may have evolved as the "easiest way to publish". 

*Although some Apache/Jakarta decisions are simply baffling to me (Moin
Moin powered by Pything instead of a free intance of Confluence built in
100% java, for example.)


Cheers,
Timo
P.S. I haven't forgotten about my offer to try and help create a css
layout and printable stylesheet for the docs.... so many ideas, so
little time. 

---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org


Re: generated docs in repo

Posted by Mike Kienenberger <mk...@alaska.net>.
Nathan Bubna <nb...@gmail.com> wrote:
> it might be nice to include some policy on published documentation
> along with that.  at present, we have docs for velocity 1.5 published
> when we haven't even released 1.5 yet.  this has confused many who
> can't understand why the map syntax doesn't work in 1.4.

For Cayenne, we put the version number next to the api docs, and supply 
multiple versions.

Javadoc API - 1.1
Javadoc API - 1.0 

For the User/Developer/Modeler guide, we clearly indicate the version number 
at the top of the front page (and at the top along the right-hand side where 
we have a TOC menu): User Guide - version 1.1.   We only have the latest 
released version on the web page for those docs.

There are no version indicators on any of the velocity docs.   Fixing that 
issue would be a helpful start :)

---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org


Re: generated docs in repo

Posted by Will Glass-Husain <wg...@forio.com>.
Good discussion.  My comments below.  Also a +1 on labeling versions on 
docs.

My next assualt on the todo's will be related to this.

WILL

----- Original Message ----- 
From: "Nathan Bubna" <nb...@gmail.com>
> 1.  published javadoc and user's guide type stuff should match latest
> released version (including betas and release candidates to encourage
> early adoption).
+1

> 2.  published change log or other "news" type pages should be
> regularly updated to show changes since last release (also to
> encourage early adoption)

+1.  I did this recently (updated change log).  I'd like to reformat this, 
tie it closer to the issues list

> 3.  typos in published javadoc or user's guide should be fixed to
> match latest release's actual functioning, even if that puts them at
> odds with the docs bundled along with that release.

+1 on concept, but not sure how we'd manage this.  Does this mean we need to 
keep the branches up to date?  Could get confusing.

> 4.  any docs that do not reflect the latest release--whether because
> they are obsolete or cutting edge--should not be placed or left up on
> the project web site

+1.  Great idea.  We've already talked about getting rid of the 
specifications docs. 


---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org


Re: generated docs in repo

Posted by Will Glass-Husain <wg...@forio.com>.
Incidentally I did a quick peek through source control to see what other 
Jakarta and Apache Java projects do.  A random sampling...

Includes HTML in source control
-----
Jakarta-Site
Struts
Lucene
Ant
Log4j
Tomcat

Doesn't include HTML in source control
----
Turbine
Geronimo
Maven

So it looks like if we pull the HTML out of the repo, we'll be in the 
minority but not alone.

WILL


----- Original Message ----- 
From: "Nathan Bubna" <nb...@gmail.com>
To: "Velocity Developers List" <ve...@jakarta.apache.org>
Sent: Thursday, February 17, 2005 12:11 PM
Subject: Re: generated docs in repo


> On Thu, 17 Feb 2005 09:33:07 -0800, Will Glass-Husain <wg...@forio.com> 
> wrote:
>> Well, bottom line is that there's only 5 people  people who have the 
>> ability
>> to update the Velocity site.  (3 Velocity committers and 2 tools
>> committers - is that right?)
>
> sorta.  but Marino and i can really only edit the tools docs given the
> current publishing system.  since we can't commit to the core, we
> can't update and commit new core docs either.
>
>> I vote with Nathan to leave out the generated docs.  (That's two).  It's
>> easy enough to create them on demand.  Any of the other committers 
>> available
>> to comment?
>>
>> As a side note, we should be sure it's clearly stated in the readme how 
>> to
>> make the docs for those brave enough to download the nightly source 
>> drops.
>> (And of course the docs should be generated for released versions).
>
> it might be nice to include some policy on published documentation
> along with that.  at present, we have docs for velocity 1.5 published
> when we haven't even released 1.5 yet.  this has confused many who
> can't understand why the map syntax doesn't work in 1.4.
>
> here's a quick, unrefined suggestion for a web site/publishing policy:
>
> 1.  published javadoc and user's guide type stuff should match latest
> released version (including betas and release candidates to encourage
> early adoption).
>
> 2.  published change log or other "news" type pages should be
> regularly updated to show changes since last release (also to
> encourage early adoption)
>
> 3.  typos in published javadoc or user's guide should be fixed to
> match latest release's actual functioning, even if that puts them at
> odds with the docs bundled along with that release.
>
> 4.  any docs that do not reflect the latest release--whether because
> they are obsolete or cutting edge--should not be placed or left up on
> the project web site
>
> thoughts?
>
>> Best,
>> WILL
>>
>> ----- Original Message -----
>> From: "Florin Vancea" <fv...@maxiq.ro>
>> To: "Velocity Developers List" <ve...@jakarta.apache.org>
>> Sent: Thursday, February 17, 2005 8:36 AM
>> Subject: Re: generated docs in repo
>>
>> > Suggestion (may be foolish, since I'm not familiar with Apache's 
>> > internal
>> > workings):
>> >
>> > Split the docs in a completely separate repository tree and let the
>> > developers check in and work with the "unpolluted" pure source in the
>> > remaining tree.
>> > At build time, generate docs in the "doc" tree from sources and commit
>> > them,
>> > keeping the simple_publishing_method happy.
>> >
>> > Just my 2c.
>> >
>> > Florin.
>> >
>> > ----- Original Message -----
>> > From: "Tim Colson (tcolson)" <tc...@cisco.com>
>> > To: "Velocity Developers List" <ve...@jakarta.apache.org>
>> > Sent: Thursday, February 17, 2005 6:28 PM
>> > Subject: RE: generated docs in repo
>> >
>> >
>> >>
>> >> > > Which brings me back to the question:  Do we really want
>> >> > > *auto-generated* documents in the repo?
>> >> >
>> >> > for the record, i've been told that this was done to make updating 
>> >> > the
>> >> > site "easier".  rather than uploading the generated docs to the site
>> >> > directly, we check them in to the repo and just do a cvs (or svn)
>> >> > update of them at the web site's root.  but personally, i've never
>> >> > been convinced that this is that much easier.
>> >>
>> >> I'm in the same boat as Shinobu... seems anything that can be 
>> >> generated
>> >> doesn't belong in the repo. But based on Nathans info, I can 
>> >> understand
>> >> reasons* why it may have evolved as the "easiest way to publish".
>> >>
>> >> *Although some Apache/Jakarta decisions are simply baffling to me 
>> >> (Moin
>> >> Moin powered by Pything instead of a free intance of Confluence built 
>> >> in
>> >> 100% java, for example.)
>> >>
>> >>
>> >> Cheers,
>> >> Timo
>> >> P.S. I haven't forgotten about my offer to try and help create a css
>> >> layout and printable stylesheet for the docs.... so many ideas, so
>> >> little time.
>> >>
>> >> ---------------------------------------------------------------------
>> >> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
>> >> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>> >>
>> >>
>> >
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
>> > For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org


Re: generated docs in repo

Posted by Nathan Bubna <nb...@gmail.com>.
On Thu, 17 Feb 2005 09:33:07 -0800, Will Glass-Husain <wg...@forio.com> wrote:
> Well, bottom line is that there's only 5 people  people who have the ability
> to update the Velocity site.  (3 Velocity committers and 2 tools
> committers - is that right?)

sorta.  but Marino and i can really only edit the tools docs given the
current publishing system.  since we can't commit to the core, we
can't update and commit new core docs either.
 
> I vote with Nathan to leave out the generated docs.  (That's two).  It's
> easy enough to create them on demand.  Any of the other committers available
> to comment?
> 
> As a side note, we should be sure it's clearly stated in the readme how to
> make the docs for those brave enough to download the nightly source drops.
> (And of course the docs should be generated for released versions).

it might be nice to include some policy on published documentation
along with that.  at present, we have docs for velocity 1.5 published
when we haven't even released 1.5 yet.  this has confused many who
can't understand why the map syntax doesn't work in 1.4.

here's a quick, unrefined suggestion for a web site/publishing policy:

1.  published javadoc and user's guide type stuff should match latest
released version (including betas and release candidates to encourage
early adoption).

2.  published change log or other "news" type pages should be
regularly updated to show changes since last release (also to
encourage early adoption)

3.  typos in published javadoc or user's guide should be fixed to
match latest release's actual functioning, even if that puts them at
odds with the docs bundled along with that release.

4.  any docs that do not reflect the latest release--whether because
they are obsolete or cutting edge--should not be placed or left up on
the project web site

thoughts?

> Best,
> WILL
> 
> ----- Original Message -----
> From: "Florin Vancea" <fv...@maxiq.ro>
> To: "Velocity Developers List" <ve...@jakarta.apache.org>
> Sent: Thursday, February 17, 2005 8:36 AM
> Subject: Re: generated docs in repo
> 
> > Suggestion (may be foolish, since I'm not familiar with Apache's internal
> > workings):
> >
> > Split the docs in a completely separate repository tree and let the
> > developers check in and work with the "unpolluted" pure source in the
> > remaining tree.
> > At build time, generate docs in the "doc" tree from sources and commit
> > them,
> > keeping the simple_publishing_method happy.
> >
> > Just my 2c.
> >
> > Florin.
> >
> > ----- Original Message -----
> > From: "Tim Colson (tcolson)" <tc...@cisco.com>
> > To: "Velocity Developers List" <ve...@jakarta.apache.org>
> > Sent: Thursday, February 17, 2005 6:28 PM
> > Subject: RE: generated docs in repo
> >
> >
> >>
> >> > > Which brings me back to the question:  Do we really want
> >> > > *auto-generated* documents in the repo?
> >> >
> >> > for the record, i've been told that this was done to make updating the
> >> > site "easier".  rather than uploading the generated docs to the site
> >> > directly, we check them in to the repo and just do a cvs (or svn)
> >> > update of them at the web site's root.  but personally, i've never
> >> > been convinced that this is that much easier.
> >>
> >> I'm in the same boat as Shinobu... seems anything that can be generated
> >> doesn't belong in the repo. But based on Nathans info, I can understand
> >> reasons* why it may have evolved as the "easiest way to publish".
> >>
> >> *Although some Apache/Jakarta decisions are simply baffling to me (Moin
> >> Moin powered by Pything instead of a free intance of Confluence built in
> >> 100% java, for example.)
> >>
> >>
> >> Cheers,
> >> Timo
> >> P.S. I haven't forgotten about my offer to try and help create a css
> >> layout and printable stylesheet for the docs.... so many ideas, so
> >> little time.
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> >> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
> >>
> >>
> >
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
> >
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
> 
>

---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org


Re: generated docs in repo

Posted by Will Glass-Husain <wg...@forio.com>.
Well, bottom line is that there's only 5 people  people who have the ability 
to update the Velocity site.  (3 Velocity committers and 2 tools 
committers - is that right?)

I vote with Nathan to leave out the generated docs.  (That's two).  It's 
easy enough to create them on demand.  Any of the other committers available 
to comment?

As a side note, we should be sure it's clearly stated in the readme how to 
make the docs for those brave enough to download the nightly source drops. 
(And of course the docs should be generated for released versions).

Best,
WILL

----- Original Message ----- 
From: "Florin Vancea" <fv...@maxiq.ro>
To: "Velocity Developers List" <ve...@jakarta.apache.org>
Sent: Thursday, February 17, 2005 8:36 AM
Subject: Re: generated docs in repo


> Suggestion (may be foolish, since I'm not familiar with Apache's internal
> workings):
>
> Split the docs in a completely separate repository tree and let the
> developers check in and work with the "unpolluted" pure source in the
> remaining tree.
> At build time, generate docs in the "doc" tree from sources and commit 
> them,
> keeping the simple_publishing_method happy.
>
> Just my 2c.
>
> Florin.
>
> ----- Original Message ----- 
> From: "Tim Colson (tcolson)" <tc...@cisco.com>
> To: "Velocity Developers List" <ve...@jakarta.apache.org>
> Sent: Thursday, February 17, 2005 6:28 PM
> Subject: RE: generated docs in repo
>
>
>>
>> > > Which brings me back to the question:  Do we really want
>> > > *auto-generated* documents in the repo?
>> >
>> > for the record, i've been told that this was done to make updating the
>> > site "easier".  rather than uploading the generated docs to the site
>> > directly, we check them in to the repo and just do a cvs (or svn)
>> > update of them at the web site's root.  but personally, i've never
>> > been convinced that this is that much easier.
>>
>> I'm in the same boat as Shinobu... seems anything that can be generated
>> doesn't belong in the repo. But based on Nathans info, I can understand
>> reasons* why it may have evolved as the "easiest way to publish".
>>
>> *Although some Apache/Jakarta decisions are simply baffling to me (Moin
>> Moin powered by Pything instead of a free intance of Confluence built in
>> 100% java, for example.)
>>
>>
>> Cheers,
>> Timo
>> P.S. I haven't forgotten about my offer to try and help create a css
>> layout and printable stylesheet for the docs.... so many ideas, so
>> little time.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>>
>>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
> 


---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org


Re: generated docs in repo

Posted by Florin Vancea <fv...@maxiq.ro>.
Suggestion (may be foolish, since I'm not familiar with Apache's internal
workings):

Split the docs in a completely separate repository tree and let the
developers check in and work with the "unpolluted" pure source in the
remaining tree.
At build time, generate docs in the "doc" tree from sources and commit them,
keeping the simple_publishing_method happy.

Just my 2c.

Florin.

----- Original Message ----- 
From: "Tim Colson (tcolson)" <tc...@cisco.com>
To: "Velocity Developers List" <ve...@jakarta.apache.org>
Sent: Thursday, February 17, 2005 6:28 PM
Subject: RE: generated docs in repo


>
> > > Which brings me back to the question:  Do we really want
> > > *auto-generated* documents in the repo?
> >
> > for the record, i've been told that this was done to make updating the
> > site "easier".  rather than uploading the generated docs to the site
> > directly, we check them in to the repo and just do a cvs (or svn)
> > update of them at the web site's root.  but personally, i've never
> > been convinced that this is that much easier.
>
> I'm in the same boat as Shinobu... seems anything that can be generated
> doesn't belong in the repo. But based on Nathans info, I can understand
> reasons* why it may have evolved as the "easiest way to publish".
>
> *Although some Apache/Jakarta decisions are simply baffling to me (Moin
> Moin powered by Pything instead of a free intance of Confluence built in
> 100% java, for example.)
>
>
> Cheers,
> Timo
> P.S. I haven't forgotten about my offer to try and help create a css
> layout and printable stylesheet for the docs.... so many ideas, so
> little time.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
>
>



---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org