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/
