You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by haleh mahbod <hm...@gmail.com> on 2009/01/07 22:05:10 UTC
Versioned Documentation by SCA Java Releases
Hi,
The request for "better documentation" was amongst the top ranked feedback
that we received from the user survey in December. I am starting to work on
this (with your help of course).
One of the first steps is to establish a mechanism to have current and up to
date documentation for each release. As it stands today, we have one version
of the documentation that is called the latest [1]. Sometimes the content is
ahead of the latest implementation and we have notes in the docs that state
"not all is implemented yet". This worked fine for a while, but now that 1.x
is maturing and 2.x is staring, it will cause confusion.
Can we agree that moving forward we would have documentation per major (x.x)
release?
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.
- The "downloads and documentation page" [1] would still point to
the latest release and documentation for quick reference, but the release
pages would need to link to the related documentation as well. In example
[2], the page would include a link to its documentation. This ensures that
the archived releases have their corresponding documentation linked into
them.
- The "downloads and documentation page" [1] would have SCA java
1.x and SCA Java 2.x rows. Each pointing to the latest 1.x or 2.x release
and documentation.
- When a release is finished, a new documentation space gets
started for the next release which will capture the work for the next
release. This is a more proactive approach to collecting information over
the release cycle rather than creating documentation at the tail end of the
release.
Does this sound reasonable?
[1]: http://tuscany.apache.org/tuscany-downloads-documentations.html
[2]: http://tuscany.apache.org/sca-java-releases.html
Re: Versioned Documentation by SCA Java Releases
Posted by Dan Becker <da...@gmail.com>.
haleh mahbod wrote:
> 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) ?
>> Yes. Typically 1.x.x contains bug fixes and no major features.
>
> 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 is a problem that we are trying to solve. So, today if someone gets
> 1.1, documentation is at 1.4 level. It is confusing.
I am in favor of documentation wikis per release as long as it is done
at the point release or major release and not minor point release (e.g.
done at 1.3, 1.4, 1.5, 2.0, but not 1.4.1 and 1.4.2).
I also would prefer that the point release documentation become a
historical snapshot. I would hate to see dual maintenance on older
documentation snapshots.
One side comment. I cringe when I see TO-DO and TO-BE-DONE and
NOT-YET-IMPLEMENTED comments in documentation. These should be used
sparingly, perhaps as a reminder to the reader that a certain important
feature that might be expected is not available in Tuscany. They should
be there for the benefit of the reader, and not as a note to the next
editor to clean up. (Sorry, this sounds like a rant, but I'm not venting
at anyone in particular. I just want to add a helpful reminder.)
--
Thanks, Dan Becker
Re: Versioned Documentation by SCA Java Releases
Posted by haleh mahbod <hm...@gmail.com>.
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) ?
> Yes. Typically 1.x.x contains bug fixes and no major features.
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 is a problem that we are trying to solve. So, today if someone gets
1.1, documentation is at 1.4 level. It is confusing.
As for the space, we can talk about how to do this effectively so that we
don't waste a lot of space in another thread.
On Wed, Jan 7, 2009 at 2:03 PM, Luciano Resende <lu...@gmail.com>wrote:
> > On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> 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/
>
Re: Versioned Documentation by SCA Java Releases
Posted by Luciano Resende <lu...@gmail.com>.
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 <an...@gmail.com> 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 <hm...@gmail.com> 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 <lu...@gmail.com>
>> wrote:
>>>
>>> On Fri, Jan 9, 2009 at 8:27 AM, haleh mahbod <hm...@gmail.com> 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 <si...@googlemail.com>
>>> > wrote:
>>> >>
>>> >>
>>> >> On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <hm...@gmail.com>
>>> >> 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 <en...@gmail.com>
>>> >>> 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" <lu...@gmail.com>
>>> >>>> Sent: Wednesday, January 07, 2009 2:03 PM
>>> >>>> To: <de...@tuscany.apache.org>
>>> >>>> Subject: Re: Versioned Documentation by SCA Java Releases
>>> >>>>
>>> >>>>>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com>
>>> >>>>>> 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/
Re: Versioned Documentation by SCA Java Releases
Posted by ant elder <an...@gmail.com>.
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 <hm...@gmail.com> 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 <lu...@gmail.com>wrote:
>
>> On Fri, Jan 9, 2009 at 8:27 AM, haleh mahbod <hm...@gmail.com> 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 <si...@googlemail.com>
>> > wrote:
>> >>
>> >>
>> >> On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <hm...@gmail.com>
>> 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 <en...@gmail.com>
>> 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" <lu...@gmail.com>
>> >>>> Sent: Wednesday, January 07, 2009 2:03 PM
>> >>>> To: <de...@tuscany.apache.org>
>> >>>> Subject: Re: Versioned Documentation by SCA Java Releases
>> >>>>
>> >>>>>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com>
>> >>>>>> 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/
>>
>
>
Re: Versioned Documentation by SCA Java Releases
Posted by haleh mahbod <hm...@gmail.com>.
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 <lu...@gmail.com>wrote:
> On Fri, Jan 9, 2009 at 8:27 AM, haleh mahbod <hm...@gmail.com> 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 <si...@googlemail.com>
> > wrote:
> >>
> >>
> >> On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <hm...@gmail.com>
> 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 <en...@gmail.com>
> 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" <lu...@gmail.com>
> >>>> Sent: Wednesday, January 07, 2009 2:03 PM
> >>>> To: <de...@tuscany.apache.org>
> >>>> Subject: Re: Versioned Documentation by SCA Java Releases
> >>>>
> >>>>>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com>
> >>>>>> 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/
>
Re: Versioned Documentation by SCA Java Releases
Posted by Luciano Resende <lu...@gmail.com>.
On Fri, Jan 9, 2009 at 8:27 AM, haleh mahbod <hm...@gmail.com> 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 <si...@googlemail.com>
> wrote:
>>
>>
>> On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <hm...@gmail.com> 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 <en...@gmail.com> 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" <lu...@gmail.com>
>>>> Sent: Wednesday, January 07, 2009 2:03 PM
>>>> To: <de...@tuscany.apache.org>
>>>> Subject: Re: Versioned Documentation by SCA Java Releases
>>>>
>>>>>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com>
>>>>>> 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/
Re: Versioned Documentation by SCA Java Releases
Posted by haleh mahbod <hm...@gmail.com>.
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<http://tuscany.apache.org/sca-java-bindingjms.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.
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 <si...@googlemail.com>wrote:
>
>
> On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <hm...@gmail.com> 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 <en...@gmail.com> 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" <lu...@gmail.com>
>>> Sent: Wednesday, January 07, 2009 2:03 PM
>>> To: <de...@tuscany.apache.org>
>>> Subject: Re: Versioned Documentation by SCA Java Releases
>>>
>>>
>>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> 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/1.x-docs/sca-java-bindingjms.html>
> http://tuscany.apache.org/2.x-docs/<http://tuscany.apache.org/1.x-docs/sca-java-bindingjms.html>extensionguide
>
> http://tuscany.apache.org/2.x-docs/<http://tuscany.apache.org/1.x-docs/sca-java-bindingjms.html>
> extensionguide/sca-java-bindingjms.html<http://tuscany.apache.org/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/<http://tuscany.apache.org/1.x-docs/sca-java-bindingjms.html>
> extensionguide/sca-java-bindingjms.html<http://tuscany.apache.org/sca-java-bindingjms.html>
>
> Simon
>
>
Re: Versioned Documentation by SCA Java Releases
Posted by Simon Laws <si...@googlemail.com>.
On Wed, Jan 7, 2009 at 10:53 PM, haleh mahbod <hm...@gmail.com> 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 <en...@gmail.com> 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" <lu...@gmail.com>
>> Sent: Wednesday, January 07, 2009 2:03 PM
>> To: <de...@tuscany.apache.org>
>> Subject: Re: Versioned Documentation by SCA Java Releases
>>
>>
>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> 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/1.x-docs/sca-java-bindingjms.html>
http://tuscany.apache.org/2.x-docs/<http://tuscany.apache.org/1.x-docs/sca-java-bindingjms.html>extensionguide
http://tuscany.apache.org/2.x-docs/<http://tuscany.apache.org/1.x-docs/sca-java-bindingjms.html>
extensionguide/sca-java-bindingjms.html<http://tuscany.apache.org/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/<http://tuscany.apache.org/1.x-docs/sca-java-bindingjms.html>
extensionguide/sca-java-bindingjms.html<http://tuscany.apache.org/sca-java-bindingjms.html>
Simon
Re: Versioned Documentation by SCA Java Releases
Posted by haleh mahbod <hm...@gmail.com>.
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 <en...@gmail.com> 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" <lu...@gmail.com>
> Sent: Wednesday, January 07, 2009 2:03 PM
> To: <de...@tuscany.apache.org>
> Subject: Re: Versioned Documentation by SCA Java Releases
>
>
> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> 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/
>>
>
>
Re: Versioned Documentation by SCA Java Releases
Posted by Raymond Feng <en...@gmail.com>.
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" <lu...@gmail.com>
Sent: Wednesday, January 07, 2009 2:03 PM
To: <de...@tuscany.apache.org>
Subject: Re: Versioned Documentation by SCA Java Releases
>> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> 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/
Re: Versioned Documentation by SCA Java Releases
Posted by Luciano Resende <lu...@gmail.com>.
> On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> 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/
Re: Versioned Documentation by SCA Java Releases
Posted by ant elder <an...@gmail.com>.
On Wed, Jan 7, 2009 at 9:05 PM, haleh mahbod <hm...@gmail.com> wrote:
> Hi,
>
> The request for "better documentation" was amongst the top ranked feedback
> that we received from the user survey in December. I am starting to work on
> this (with your help of course).
>
>
>
> One of the first steps is to establish a mechanism to have current and up
> to date documentation for each release. As it stands today, we have one
> version of the documentation that is called the latest [1]. Sometimes the
> content is ahead of the latest implementation and we have notes in the docs
> that state "not all is implemented yet". This worked fine for a while, but
> now that 1.x is maturing and 2.x is staring, it will cause confusion.
>
>
> Can we agree that moving forward we would have documentation per major
> (x.x) release?
>
>
>
> 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.
>
> - The "downloads and documentation page" [1] would still point to
> the latest release and documentation for quick reference, but the release
> pages would need to link to the related documentation as well. In example
> [2], the page would include a link to its documentation. This ensures that
> the archived releases have their corresponding documentation linked into
> them.
>
> - The "downloads and documentation page" [1] would have SCA java
> 1.x and SCA Java 2.x rows. Each pointing to the latest 1.x or 2.x release
> and documentation.
>
> - When a release is finished, a new documentation space gets
> started for the next release which will capture the work for the next
> release. This is a more proactive approach to collecting information over
> the release cycle rather than creating documentation at the tail end of the
> release.
>
>
>
> Does this sound reasonable?
>
>
>
> [1]: http://tuscany.apache.org/tuscany-downloads-documentations.html
>
> [2]: http://tuscany.apache.org/sca-java-releases.html
>
That all sounds reasonable to me. It might end up with quite a lot of wiki
spaces over time so we may need to check with the confluence admin folks if
there's any issues with doing that, but with our current rate of major
releases its not going to be a problem in the near future so I say go for
it.
...ant