Actually users had asked for downloadable docs. I looked at the pdf. It is including the left bar of the website. If we could get rid of that, it is a good idea. Thanks for looking into it.
The only caveat is that we can't change the docs after a release if there are problems and docs must be done at the same time as a release is ready. On Fri, Jan 9, 2009 at 10:13 AM, Luciano Resende <[email protected]>wrote: > On Fri, Jan 9, 2009 at 8:27 AM, haleh mahbod <[email protected]> wrote: > > Here is what I had in mind. I am not sure how well it'll work, but we can > > give it a try and change if it does not work. Goal of this approach is > to > > not use too much space. > > > > > > We create a new top level page for extensions and user guide for each > major > > (x.x) release. The top level links to many 'informational' pages that > could > > become release specific. > > If the documentation for an informational page, like the jms one you > > mentioned, will have to change for the given release, a copy of it will > made > > called sca-java-bindingjms-x.x.html. Notice the version number. Changes > will > > be made in this page. > > Therefore, at the end, when the release is ready, the TOC will be > pointing > > to pages that are x.x (because we updated them for the release) or older > > versions. > > > > How about having only one version of the documentation for 1.x, that > represents the current status of a given piece of documentation (e.g > sca-java-bindings.html). Then when we cut the release, we export the > documentation piece as a PDF and include it to the release > distribution. > > I have made a quick test on how to export the documentation contents > to PDF [1], and it looks like this can be an option, but it might > imply we need to change the format of our documentation pages, to > remove the website outline menu from the page contents. > > Another export option might be to just use the HTML Exported contents > (e.g similar to our website contents) and ship that as the snapshot of > the documentation on a given release. > > [1] > http://people.apache.org/~lresende/tuscany/doc/TUSCANY-20090109-09_58_51.pdf > > > So, over time, some pages will stay the same and some that related to > > evolving features will have new versions for each release. > > > > Now, what I meant by faithfully updating the docs is following the above > > steps.That's all. > > Does this make sense? > > > > On Fri, Jan 9, 2009 at 5:47 AM, Simon Laws <[email protected]> > > wrote: > >> > >> > >> On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <[email protected]> > wrote: > >>> > >>> Now you are getting into how to do this which I intended to carry on in > >>> another thread. Yes, we can, but we need to follow the principle of > >>> replacing the pages that need update faithfully. So, at the start, the > top > >>> level is different and everything else is the same. Over time, the > specific > >>> documentation pages would get replaced (not updated) with the new > version > >>> for that specific release. At the end of each release, some pages > remain the > >>> same and some will be updated for the current release. We also need to > make > >>> sure the subsequent release documentation is built on top of the latest > one. > >>> > >>> On Wed, Jan 7, 2009 at 2:33 PM, Raymond Feng <[email protected]> > wrote: > >>>> > >>>> Cannot we just have separate top-level pages to contain the document > >>>> hierarchy for different releases instead of multiple wiki spaces? For > >>>> example, we can have sca-java-1.x and sca-java-2.x. > >>>> > >>>> Thanks, > >>>> Raymond > >>>> -------------------------------------------------- > >>>> From: "Luciano Resende" <[email protected]> > >>>> Sent: Wednesday, January 07, 2009 2:03 PM > >>>> To: <[email protected]> > >>>> Subject: Re: Versioned Documentation by SCA Java Releases > >>>> > >>>>>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <[email protected]> > >>>>>> wrote: > >>>>>> This means a few things: > >>>>>> > >>>>>> - We need to have a wiki space per release. Let's talk > about > >>>>>> how > >>>>>> to do this in another thread if there is agreement to go ahead. > >>>>>> > >>>>> > >>>>> Trying to understand your definition for "one wiki space per > release". > >>>>> So, in the scenario where we would have 1.4, 1.4.1, 1.5 and 2.0 these > >>>>> means 3 documentation wikis (1.4, 1.5 and 2.0) ? > >>>>> > >>>>> Another option would be to have a 1.x and 2.x and each release ship a > >>>>> snapshot of the wiki as it's documentation, this way we would > probably > >>>>> reduce the admin and documentation work needed. But we would need to > >>>>> investigate how we would "ship the snapshot" of the documentation. > >>>>> > >>>>> > >>>>> -- > >>>>> Luciano Resende > >>>>> Apache Tuscany, Apache PhotArk > >>>>> http://people.apache.org/~lresende > >>>>> http://lresende.blogspot.com/ > >>>> > >>> > >> Haleh > >> > >> I think I'm with you here but can you confirm what you mean by > "principle > >> of replacing the pages that need update faithfully". In particular I > don't > >> quite get "update faithfully"? > >> > >> For example, At the moment we have the jms binding documentation at > >> > >> http://tuscany.apache.org/sca-java-bindingjms.html > >> > >> Are you suggesting that we start with; > >> > >> http://tuscany.apache.org/2.x-docs/ > >> http://tuscany.apache.org/2.x-docs/extensionguide > >> > http://tuscany.apache.org/2.x-docs/extensionguide/sca-java-bindingjms.html > >> which actually refers to > http://tuscany.apache.org/sca-java-bindingjms.html > >> (i.e. the 1.x version) in the first instance > >> > >> Then when we make 2.x specific changes to the JMS binding we change the > >> docs to have a new and separate > >> > >> > http://tuscany.apache.org/2.x-docs/extensionguide/sca-java-bindingjms.html > >> > >> Simon > >> > > > > > > > > -- > Luciano Resende > Apache Tuscany, Apache PhotArk > http://people.apache.org/~lresende > http://lresende.blogspot.com/ >
