axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Chatra Nakkawita" <cha...@gmail.com>
Subject Re: [Axis2] Why do we have multiple versions of docs in xdocs
Date Wed, 22 Mar 2006 05:02:42 GMT
hey ajith,
you did hear my reply...may be not on mail. but i did +1 chinthaka's
solution.

anyways for the record.... here goes:

one thing i have to make clear is that once a release has been made and the
code frozen it is very impractical to think that you can freeze the
documentaion with it. may be you can do that if you are planning to actually
make the release one week after the code freeze or something like that.

the only way u can even mention about a critical errors on the release
(code) is through documentaion. so it is unfair and unrealistic to think
that u can freeze documentaion with a release. the docs of the latest
released should be easily available for anyone to commit and make a
correction or critical improvement.

we have a web site to give ppl information and instructions on product,
therefore any documentaion/content that goes on it is subjected to
improvements and error corrections. more or less it is the right of the
reader/audience to get accurate & user friendly documentaion.

or what would u suggest have another page carrying infor on errors of
product/project documentaion that's published on site.

you must give freedom to correct errors on docs published on site.

i agree that carrying previous versions on xdocs will make a check out
heavy. so like v agreed (chinthaka's last mail) the compromise will be to
have docs for latest version released and the docs of the version v are
currently working on (for next release). that makes great sense to me.

you must include the docs of latest released version in xdocs because it is
going to be subjected to error corrections and improvements after the
release as i mentioned earlier. and for obvious reasons v need to have docs
of the next release v are working on.

so lets just have 2 dirs containing docs of two release (latest released and
next to be released)......it sounds pretty practical and fair enough to
everyone.

and on the site.....i agree with sanjiva....nothing should be removed from
site. URLs need to be static cos they are linked to from so many other
sites. so lets have an archive for the previous releases documentaio and
another link for current release (latest released)..... and if possible
another link for docs which are for the next upcoming relase (that's
optional).

i will be updting site for latest released docs and upcoming release docs

so there's my answer

thanks & regards,
Chatra

On 3/22/06, Ajith Ranabahu <ajith.ranabahu@gmail.com> wrote:
>
> ok,
> I guess I went overboard with my theory of strictly maintaining the
> current docs in SVN (That's no reason to pull out that old builder
> extension thing anyway :( ) but I guess I'm more biased to doing
> things the right way rather than the easy way (which is unfortunately
> not the same and sometimes the 'right' way is very subjective)
> I'm (reluctantly) ok with having two versions of documents in the
> xdocs however what I'm trying to convince the people is that it's not
> the elegant solution. With all this technology around us (SVN,maven,
> ant) we should be able to find a better solution than this :)
> However I'm not maintaining the docs so it's not my call. May it be an
> ugly solution, but if it suits the one who'll be really doing the
> work, then let it be. Having said that we are yet to hear the opinion
> of Chathra on this and I would say that is the conclusion of this
> thread
>
> Ajith
>
> On 3/21/06, Eran Chinthaka <chinthaka@opensource.lk> wrote:
> > I hope we can apply our "builder extensions" theory here, but
> > unfortunately for the same person :-D
> >
> > (for those who doesn't know what this builder extensions theory is,
> > please search for the mails of Axis2 during its start up days)
> >
> > -- Chinthaka
> >
> > Ajith Ranabahu wrote:
> > > Hi all,
> > > Ok I'm also +1 to the compromise but I have a small issue to be
> clarified.
> > > Once a release is out we do a SVN tag (and I've been told that tags
> > > automatically become branches, of which I'm not really sure about - If
> > >  not lets say we always start a branch after a tag which seems to be
> > > the right thing to do if there are continuous changes). The idea of
> > > the tag is a convenient way of retrieving the relevant version later.
> > > However if we do the updates on the main tree and not commit the same
> > > changes to the branches , the source retrieved from that branch will
> > > be inconsistent!
> > > I remember a cool feature is VSS (ok - I used to work with MSFT
> > > software sometime earlier  :)) where a source file could be shared in
> > > two locations (more like a symlink thing). If we do have something
> > > like that in SVN that'd solve our problem
> > >
> > > Ajith
> > >
> > > On 3/21/06, robert lazarski <robertlazarski@gmail.com> wrote:
> > >
> > >>  "Damn, I was going to enjoy giving boxing gloves to see open source
> > >>  developers fight about documentation!!!!!!!!!!!"
> > >>
> > >>  Or a soccer ball, since the world cup is approaching. ;-)  +1 to a
> good
> > >> compromise.
> > >>
> > >>  Robert
> > >>  http://www.braziloutsource.com/
> > >>
> > >>
> > >> On 3/21/06, Sanjiva Weerawarana < sanjiva@opensource.lk> wrote:
> > >>
> > >>> Cool :) +1.
> > >>>
> > >>> Damn, I was going to enjoy giving boxing gloves to see open source
> > >>> developers fight about documentation!!!!!!!!!!!
> > >>>
> > >>> Sanjiva.
> > >>>
> > >>> On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> > >>>
> > >>>> Ok, time to compromise  ;-)
> > >>>>
> > >>>> Lets maintain two versions of the documents inside the xdocs. One
> with
> > >>>> the *released* version of docs and the other with *latest *version
> of
> > >>>> the docs.
> > >>>>
> > >>>> And lets have all the versions of the documents in the site. *BUT,
> *we
> > >>>> will update only the documents of the last release. So the older
> > >>>> documents will be sort of archived, but the links will never
> change.
> > >>>>
> > >>>> Can we all agree to this ?
> > >>>>
> > >>>> This is my +1.
> > >>>>
> > >>>> -- Chinthaka
> > >>>>
> > >>>
> > >>
> > >
> > >
> > > --
> > > Ajith Ranabahu
> > >
> > >
> >
> >
>
>
> --
> Ajith Ranabahu
>

Mime
View raw message