[2.x] Sample docs/READMEs was - Re: [PROPOSAL] Tuscany Documentation

[Simon Laws <si...@googlemail.com>]

On Thu, Feb 5, 2009 at 8:15 AM, ant elder <an...@gmail.com> wrote:

>
>
> On Wed, Feb 4, 2009 at 5:44 PM, Dan Becker <da...@gmail.com> wrote:
>
>> Luciano Resende wrote:
>>
>>> On Wed, Feb 4, 2009 at 8:49 AM, Dan Becker <da...@gmail.com>
>>> wrote:
>>>
>>>> Luciano Resende wrote:
>>>>
>>>>> On Wed, Feb 4, 2009 at 8:08 AM, Dan Becker <da...@gmail.com>
>>>>> wrote:
>>>>>
>>>>>> Luciano Resende wrote:
>>>>>>
>>>>>>> On Wed, Feb 4, 2009 at 7:32 AM, Dan Becker <da...@gmail.com>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> This is a good proposal Luciano. I like the idea of "branching" the
>>>>>>>> docs.
>>>>>>>> Just as the Sun JDKs provide versioned docs from the 1.0 days to the
>>>>>>>> current
>>>>>>>> 1.6 days, I too would like to see versioned Tuscany docs.
>>>>>>>>
>>>>>>>> In addition to versioned wiki spaces, we might want to think about
>>>>>>>> versioned
>>>>>>>> public pages. Right now there is an export plugin that moves the
>>>>>>>> wiki
>>>>>>>> pages
>>>>>>>> to the external site html pages. Perhaps we need to branch the
>>>>>>>> tuscany
>>>>>>>> web
>>>>>>>> site so there would be a "latest" html snap shot at
>>>>>>>> http://tuscany.apache.org and earlier "versioned" html snap shots,
>>>>>>>> perhaps
>>>>>>>> at http://tuscany.apache.org/1.4, etc.
>>>>>>>>
>>>>>>>>  What problem are you trying to solve here ? Confluence is much like
>>>>>>> SVN and provides a change history for each page. Would that be ok for
>>>>>>> website ?
>>>>>>>
>>>>>> I am thinking more along the line of what the user sees for the
>>>>>> Tuscany
>>>>>> website after the wikis are exported to the world. Is the user going
>>>>>> to
>>>>>> see
>>>>>> several site versions, e.g:
>>>>>> http://tuscany.apache.org  (latest)
>>>>>> http://tuscany.apache.org/1.5 (previous release)
>>>>>> http://tuscany.apache.org/1.4 (previous release)
>>>>>>
>>>>>> Or is the user going to see several article versions on one site?,
>>>>>> e.g.:
>>>>>> http://tuscany.apache.org/sca-java-user-guide.html (latest)
>>>>>> http://tuscany.apache.org/sca-java-user-guide-1.5.html (previous
>>>>>> version)
>>>>>> http://tuscany.apache.org/sca-java-user-guide-1.4.html (previous
>>>>>> version)
>>>>>>
>>>>>>  What kind of release specific information do you think we are going
>>>>> to
>>>>> have in the website, if we remove the documentation out to the wikis ?
>>>>>
>>>>>  I don't propose removing documentation from the wikis or changing any
>>>> part
>>>> of your proposal for the wikis on the thread.
>>>>
>>>> I am just wondering what the version scheme will look like when the
>>>> various
>>>> files reach the web site. What will customers see? Where will a customer
>>>> look for articles of the 1.x flavor versus the articles of the 2.x
>>>> flavor?
>>>>
>>>>
>>> Haaa, I think I got your question now, we would have something (but
>>> probably not exactly) like this :
>>>
>>> http://db.apache.org/derby/manuals/index.html
>>>
>>> Or just a link on our website pointing to the wiki documentation
>>>
>>>
>>
>> Excellent example! I like their organization. Notice for example that the
>> developers guide follows this kind of structure for the HTML pages:
>> http://db.apache.org/derby/docs/10.3/devguide/
>> http://db.apache.org/derby/docs/10.2/devguide/
>> http://db.apache.org/derby/docs/10.1/devguide/
>>
>> This is similar to the idea I prefered above:
>>
>> >>>> http://tuscany.apache.org  (latest)
>> >>>> http://tuscany.apache.org/1.5 (previous release)
>> >>>> http://tuscany.apache.org/1.4 (previous release
>>
>> --
>> Thanks, Dan Becker
>>
>
>
> +1, would be really good if we can have the doc versioned like that on the
> website.
>
>    ...ant
>

I like Luciano's proposal. I'm mulling over the idea of putting the sample
documentation up there also as it would be a lot easier to edit and clearer
to read. We did have HTML docs a long time ago but shied away from them for
lowest common denominator reasons IIRC. I think we should revisit this
decision.

If samples pages were up on Confluence is there an easy way that the HTML
for these pages could be extracted and added to svn or even just to the
samples as the distribution is built?

Simon

Re: [2.x] Sample docs/READMEs was - Re: [PROPOSAL] Tuscany Documentation

[Simon Laws <si...@googlemail.com>]

Sorry I wasn't clear.

snip....

> putting the sample
> > documentation up there also
>

= doing it in confluence

Simon

Re: [2.x] Sample docs/READMEs was - Re: [PROPOSAL] Tuscany Documentation

[Luciano Resende <lu...@gmail.com>]

On Fri, Feb 6, 2009 at 6:26 AM, Simon Laws <si...@googlemail.com> wrote:
>
> I like Luciano's proposal. I'm mulling over the idea of putting the sample
> documentation up there also as it would be a lot easier to edit and clearer
> to read. We did have HTML docs a long time ago but shied away from them for
> lowest common denominator reasons IIRC. I think we should revisit this
> decision.
>

I don' t think we want to go back to author our content using xml/svn,
at least not me... Confluence is much easier.

> If samples pages were up on Confluence is there an easy way that the HTML
> for these pages could be extracted and added to svn or even just to the
> samples as the distribution is built?
>

The documentation pages get exported to html just as our website. That
might be the snapshot we want to put in svn during the release.

> Simon
>



-- 
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/