I agree it would be great to be able to include downlaodable doc in a release, the pdf formatting isn't very good though, i'd guess we'd be more likely to succeed with the html export though even with that we may need to do a bit of reorganizing of the website to make the export work without a lot of manual work.
Whatever, we'll still need a way to version the doc on the website and multiple wiki spaces seem like a good way to do that, i've added a JIRA to keep track of this - https://issues.apache.org/jira/browse/TUSCANY-2775 and added it to 2.0-M1 as we need somewhere to start doing some doc for the M1 release. ...ant On Sat, Jan 10, 2009 at 3:36 AM, haleh mahbod <[email protected]> wrote: > 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<http://people.apache.org/%7Elresende/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://people.apache.org/%7Elresende> >> >>>>> 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://people.apache.org/%7Elresende> >> http://lresende.blogspot.com/ >> > >
