I have installed confluence locally, and I'm prototyping some formats that would facilitate navigation throughout the documentation and still make export possible and simple. Once I get something good, I'll share with the list and we could go ahead with the creation with the new wiki spaces.
On Wed, Jan 21, 2009 at 11:42 PM, ant elder <[email protected]> wrote: > 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. > Thanks... I also agree that multiple wiki (1.x and 2.x) would be best. it would allow us to use a different navigation schema from the website and would also allow us to manage versions more easy. > ...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 >>> >>> > 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/ >> > > -- Luciano Resende Apache Tuscany, Apache PhotArk http://people.apache.org/~lresende http://lresende.blogspot.com/
