You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by ant elder <an...@gmail.com> on 2006/10/11 10:25:12 UTC
Wiki or website for doc?
Where should we be doing documentation for the M2 release function? I'd
started doing Anakia xml for the Tuscany website, but the DAS guys are using
the wiki, does this matter, should we try to be consistent? I think the
website is a better place for this type of thing, but its probably easier to
be using wiki.
...ant
Re: Wiki or website for doc?
Posted by Luciano Resende <lu...@gmail.com>.
I'd agree that wiki is a good place for collaboration and the development of
this place of documentation too. But I just want to make sure that we use
the website to have some kind of high level information, and also somewhat
detailed first steps to get people going, we could take as an example what
is available for DAS :
High Level : http://incubator.apache.org/tuscany/das_index.html
Java Overview :
http://incubator.apache.org/tuscany/java_das_overview.html
And then, what DAS has available in the Wiki :
User Guide :
http://wiki.apache.org/ws/Tuscany/TuscanyJava/DAS_Java_Overview/RDBDAS_Java_User_Guide
- Luciano Resende
On 10/11/06, Kevin Williams <ke...@qwest.net> wrote:
>
> I think the wiki is the best place for development of this type of
> documentation. It is so easy to update that I hope it will "invite"
> others to participate. I also like Venkat's idea to snapshot content
> developed on the wiki to include in a milestone distribution.
> --
> Kevin
>
>
>
>
> and I like Venkat's suggestion
>
>
>
> Rick wrote:
>
> > I don't see the need for the wiki step or harvesting. Also goes for
> pdf.
> > If a group needs to collaboratively work on a document and the wiki
> > provides them the best means for that and they want to harvest that to
> > html, I'm perfectly fine with it. But , don't see this as required
> > step, I'm perfectly fine working on the xml/html.
> >
> > Venkata Krishnan wrote:
> >
> >> Here is how I see this...
> >>
> >> - We just about create one version of the doco for which ever subject
> >> (be it
> >> about the distros or about the extensions...). This doco must be
> >> organized
> >> such that the initial sections start with some high level stuf and
> >> futher
> >> down talk about deep details.
> >> - We would then extract the high level info and put it on the website
> >> and
> >> link up to the entire doco as pdf (or anyother form) as "For more
> >> details
> >> see this....". We also package this doc with the distribution.
> >> - The Wiki is where we will collaboratively develop these docs. The
> >> content in the wiki must be harvested into the master doc that I was
> >> mentioning in the first point...
> >>
> >> I cannot think of anything else to avoid duplicating documentation.
> >>
> >> Thoughts?
> >>
> >> - Venkat
> >>
> >>
> >> On 10/11/06, Rick <cr...@gmail.com> wrote:
> >>
> >>>
> >>> I think there were still quite a few of us that saw value of doco
> >>> with in
> >>> the
> >>> distro itself.
> >>> If true, not sure how we can easily reuse the wiki work as we could
> >>> with
> >>> html.
> >>>
> >>> ant elder wrote:
> >>> > Where should we be doing documentation for the M2 release
> >>> function? I'd
> >>> > started doing Anakia xml for the Tuscany website, but the DAS guys
> >>> are
> >>> > using
> >>> > the wiki, does this matter, should we try to be consistent? I
> >>> think the
> >>> > website is a better place for this type of thing, but its probably
> >>> > easier to
> >>> > be using wiki.
> >>> >
> >>> > ...ant
> >>> >
> >>>
> >>> ---------------------------------------------------------------------
> >>> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> >>> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
> >>>
> >>>
> >>
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> > For additional commands, e-mail: tuscany-dev-help@ws.apache.org
> >
> >
> >
> >
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
>
Re: Wiki or website for doc?
Posted by Oisin Hurley <oh...@iona.com>.
> I think the wiki is the best place for development of this type of
> documentation. It is so easy to update that I hope it will
> "invite" others to participate. I also like Venkat's idea to
> snapshot content developed on the wiki to include in a milestone
> distribution.
Just a point on this one - wiki is a good place to do stuff, easy to
update, etc,
but it's important to remember that it does not lend itself naturally
to the
provision of docs that follow the 'usual' table-of-contents style
approach we
see in tech docs -- instead it is more bazaar than cathedral. So - if
you have
a vision of producing 'natural' PDF docs for offline use, then one
needs must
layer some behaviour on the wiki editing, like keeping a toc up to
date etc.
cheers
--oh
----
+353 1 637 2639
http://blogs.iona.com/ohurley
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Wiki or website for doc?
Posted by Dan Murphy <dm...@googlemail.com>.
I was looking at the Java SDO wiki...
there is a lot of overlap between the web site and the wiki... should we
clean up the wiki and link to the web site where appropriate (get rid of the
duplication) ?
Thanks in advance
Dan
Re: Wiki or website for doc?
Posted by Simon Nash <na...@hursley.ibm.com>.
I would like to contribute the documentation I am developing to the
wiki so that it can be harvested. I am currently writing basic
documentation on how to install and run Tuscany applications.
Simon
Kevin Williams wrote:
> I think the wiki is the best place for development of this type of
> documentation. It is so easy to update that I hope it will "invite"
> others to participate. I also like Venkat's idea to snapshot content
> developed on the wiki to include in a milestone distribution.
> --
> Kevin
>
>
>
>
> and I like Venkat's suggestion
>
>
>
> Rick wrote:
>
>> I don't see the need for the wiki step or harvesting. Also goes for pdf.
>> If a group needs to collaboratively work on a document and the wiki
>> provides them the best means for that and they want to harvest that to
>> html, I'm perfectly fine with it. But , don't see this as required
>> step, I'm perfectly fine working on the xml/html.
>>
>> Venkata Krishnan wrote:
>>
>>> Here is how I see this...
>>>
>>> - We just about create one version of the doco for which ever subject
>>> (be it
>>> about the distros or about the extensions...). This doco must be
>>> organized
>>> such that the initial sections start with some high level stuf and
>>> futher
>>> down talk about deep details.
>>> - We would then extract the high level info and put it on the website
>>> and
>>> link up to the entire doco as pdf (or anyother form) as "For more
>>> details
>>> see this....". We also package this doc with the distribution.
>>> - The Wiki is where we will collaboratively develop these docs. The
>>> content in the wiki must be harvested into the master doc that I was
>>> mentioning in the first point...
>>>
>>> I cannot think of anything else to avoid duplicating documentation.
>>>
>>> Thoughts?
>>>
>>> - Venkat
>>>
>>>
>>> On 10/11/06, Rick <cr...@gmail.com> wrote:
>>>
>>>>
>>>> I think there were still quite a few of us that saw value of doco
>>>> with in
>>>> the
>>>> distro itself.
>>>> If true, not sure how we can easily reuse the wiki work as we could
>>>> with
>>>> html.
>>>>
>>>> ant elder wrote:
>>>> > Where should we be doing documentation for the M2 release
>>>> function? I'd
>>>> > started doing Anakia xml for the Tuscany website, but the DAS guys
>>>> are
>>>> > using
>>>> > the wiki, does this matter, should we try to be consistent? I
>>>> think the
>>>> > website is a better place for this type of thing, but its probably
>>>> > easier to
>>>> > be using wiki.
>>>> >
>>>> > ...ant
>>>> >
>>>>
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Wiki or website for doc?
Posted by Kevin Williams <ke...@qwest.net>.
I think the wiki is the best place for development of this type of
documentation. It is so easy to update that I hope it will "invite"
others to participate. I also like Venkat's idea to snapshot content
developed on the wiki to include in a milestone distribution.
--
Kevin
and I like Venkat's suggestion
Rick wrote:
> I don't see the need for the wiki step or harvesting. Also goes for pdf.
> If a group needs to collaboratively work on a document and the wiki
> provides them the best means for that and they want to harvest that to
> html, I'm perfectly fine with it. But , don't see this as required
> step, I'm perfectly fine working on the xml/html.
>
> Venkata Krishnan wrote:
>
>> Here is how I see this...
>>
>> - We just about create one version of the doco for which ever subject
>> (be it
>> about the distros or about the extensions...). This doco must be
>> organized
>> such that the initial sections start with some high level stuf and
>> futher
>> down talk about deep details.
>> - We would then extract the high level info and put it on the website
>> and
>> link up to the entire doco as pdf (or anyother form) as "For more
>> details
>> see this....". We also package this doc with the distribution.
>> - The Wiki is where we will collaboratively develop these docs. The
>> content in the wiki must be harvested into the master doc that I was
>> mentioning in the first point...
>>
>> I cannot think of anything else to avoid duplicating documentation.
>>
>> Thoughts?
>>
>> - Venkat
>>
>>
>> On 10/11/06, Rick <cr...@gmail.com> wrote:
>>
>>>
>>> I think there were still quite a few of us that saw value of doco
>>> with in
>>> the
>>> distro itself.
>>> If true, not sure how we can easily reuse the wiki work as we could
>>> with
>>> html.
>>>
>>> ant elder wrote:
>>> > Where should we be doing documentation for the M2 release
>>> function? I'd
>>> > started doing Anakia xml for the Tuscany website, but the DAS guys
>>> are
>>> > using
>>> > the wiki, does this matter, should we try to be consistent? I
>>> think the
>>> > website is a better place for this type of thing, but its probably
>>> > easier to
>>> > be using wiki.
>>> >
>>> > ...ant
>>> >
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
>>> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>>>
>>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Wiki or website for doc?
Posted by Rick <cr...@gmail.com>.
I don't see the need for the wiki step or harvesting. Also goes for pdf.
If a group needs to collaboratively work on a document and the wiki provides
them the best means for that and they want to harvest that to html, I'm
perfectly fine with it. But , don't see this as required step, I'm perfectly
fine working on the xml/html.
Venkata Krishnan wrote:
> Here is how I see this...
>
> - We just about create one version of the doco for which ever subject
> (be it
> about the distros or about the extensions...). This doco must be organized
> such that the initial sections start with some high level stuf and futher
> down talk about deep details.
> - We would then extract the high level info and put it on the website and
> link up to the entire doco as pdf (or anyother form) as "For more details
> see this....". We also package this doc with the distribution.
> - The Wiki is where we will collaboratively develop these docs. The
> content in the wiki must be harvested into the master doc that I was
> mentioning in the first point...
>
> I cannot think of anything else to avoid duplicating documentation.
>
> Thoughts?
>
> - Venkat
>
>
> On 10/11/06, Rick <cr...@gmail.com> wrote:
>>
>> I think there were still quite a few of us that saw value of doco with in
>> the
>> distro itself.
>> If true, not sure how we can easily reuse the wiki work as we could with
>> html.
>>
>> ant elder wrote:
>> > Where should we be doing documentation for the M2 release function? I'd
>> > started doing Anakia xml for the Tuscany website, but the DAS guys are
>> > using
>> > the wiki, does this matter, should we try to be consistent? I think the
>> > website is a better place for this type of thing, but its probably
>> > easier to
>> > be using wiki.
>> >
>> > ...ant
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
>> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>>
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Wiki or website for doc?
Posted by Venkata Krishnan <fo...@gmail.com>.
Here is how I see this...
- We just about create one version of the doco for which ever subject (be it
about the distros or about the extensions...). This doco must be organized
such that the initial sections start with some high level stuf and futher
down talk about deep details.
- We would then extract the high level info and put it on the website and
link up to the entire doco as pdf (or anyother form) as "For more details
see this....". We also package this doc with the distribution.
- The Wiki is where we will collaboratively develop these docs. The
content in the wiki must be harvested into the master doc that I was
mentioning in the first point...
I cannot think of anything else to avoid duplicating documentation.
Thoughts?
- Venkat
On 10/11/06, Rick <cr...@gmail.com> wrote:
>
> I think there were still quite a few of us that saw value of doco with in
> the
> distro itself.
> If true, not sure how we can easily reuse the wiki work as we could with
> html.
>
> ant elder wrote:
> > Where should we be doing documentation for the M2 release function? I'd
> > started doing Anakia xml for the Tuscany website, but the DAS guys are
> > using
> > the wiki, does this matter, should we try to be consistent? I think the
> > website is a better place for this type of thing, but its probably
> > easier to
> > be using wiki.
> >
> > ...ant
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
>
Re: Wiki or website for doc?
Posted by Rick <cr...@gmail.com>.
I think there were still quite a few of us that saw value of doco with in the
distro itself.
If true, not sure how we can easily reuse the wiki work as we could with html.
ant elder wrote:
> Where should we be doing documentation for the M2 release function? I'd
> started doing Anakia xml for the Tuscany website, but the DAS guys are
> using
> the wiki, does this matter, should we try to be consistent? I think the
> website is a better place for this type of thing, but its probably
> easier to
> be using wiki.
>
> ...ant
>
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org