DeltaSpike docs plan

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

DeltaSpike docs plan

Rafael Benevides
Hi all,

As you may known, Red Hat docs team was called to help on DeltaSpike docs. After a long period, they have analyzed the documentation and bring us an awesome plan that is available here: https://docs.google.com/document/d/186f_amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2

The document is opened for comments.

Something that was also discussed not only inside Red Hat but with some community members is about the format and source of the documentation. I strongly believe that we should have the documentation somewhere else but the DS site source. It could improve the ease to the community to contribute with it. Having said that, it's also suggested that we should use asciidoc as documentation format.

So what we have until now ?

- The documentation plan to be reviewed and approved by the DS community. Then we can talk about the plans to make it happen.
- The documentation location: Recommendation to be out of the site source.
- The documentation format: Suggested to use asciidoc.

Please, read the plan and lets discuss about these 3 topics individually.

Michelle Murray (whose team provided the plan and she is copied on this Thread) can follow the feedback.
--

Rafael Benevides | Senior Software Engineer
JBoss Developer
M: +55-61-9269-6576

Red Hat

Better technology. Faster innovation. Powered by community collaboration.
See how it works at www.redhat.com

LinkedIn Youtube
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Gerhard Petracek
Administrator
@suggested content changes:
+1

regards,
gerhard



2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email]>:
Hi all,

As you may known, Red Hat docs team was called to help on DeltaSpike docs. After a long period, they have analyzed the documentation and bring us an awesome plan that is available here: https://docs.google.com/document/d/186f_amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2

The document is opened for comments.

Something that was also discussed not only inside Red Hat but with some community members is about the format and source of the documentation. I strongly believe that we should have the documentation somewhere else but the DS site source. It could improve the ease to the community to contribute with it. Having said that, it's also suggested that we should use asciidoc as documentation format.

So what we have until now ?

- The documentation plan to be reviewed and approved by the DS community. Then we can talk about the plans to make it happen.
- The documentation location: Recommendation to be out of the site source.
- The documentation format: Suggested to use asciidoc.

Please, read the plan and lets discuss about these 3 topics individually.

Michelle Murray (whose team provided the plan and she is copied on this Thread) can follow the feedback.
--

Rafael Benevides | Senior Software Engineer
JBoss Developer
M: <a href="tel:%2B55-61-9269-6576" value="+556192696576" target="_blank">+55-61-9269-6576



Better technology. Faster innovation. Powered by community collaboration.
See how it works at www.redhat.com


Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Rafael Benevides
Before we have a deal with Michelle's team about these content changes,
I think we should close the two other definitions:

- docs location: move to deltaspike sources, create a new repository, other?
and
-docs format: markdown or asciidoc

I believe that we should propose a vote to decided this, otherwise it
can become an endless discussion. Wdyt ?



Em 8/4/14, 17:28, Gerhard Petracek escreveu:

> @suggested content changes:
> +1
>
> regards,
> gerhard
>
>
>
> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email]
> <mailto:[hidden email]>>:
>
>     Hi all,
>
>     As you may known, Red Hat docs team was called to help on
>     DeltaSpike docs. After a long period, they have analyzed the
>     documentation and bring us an awesome plan that is available here:
>     https://docs.google.com/document/d/186f_amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>
>     The document is opened for comments.
>
>     Something that was also discussed not only inside Red Hat but with
>     some community members is about the format and source of the
>     documentation. I strongly believe that we should have the
>     documentation somewhere else but the DS site source. It could
>     improve the ease to the community to contribute with it. Having
>     said that, it's also suggested that we should use asciidoc as
>     documentation format.
>
>     So what we have until now ?
>
>     - The documentation plan to be reviewed and approved by the DS
>     community. Then we can talk about the plans to make it happen.
>     - The documentation location: Recommendation to be out of the site
>     source.
>     - The documentation format: Suggested to use asciidoc.
>
>     Please, read the plan and lets discuss about these 3 topics
>     individually.
>
>     Michelle Murray (whose team provided the plan and she is copied on
>     this Thread) can follow the feedback.
>     --
>
>     *Rafael Benevides | Senior Software Engineer*
>     JBoss Developer
>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>
>     Red Hat
>
>     Better technology. Faster innovation. Powered by community
>     collaboration.
>     See how it works at www.redhat.com <http://www.redhat.com/>
>
>     LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>     <https://www.youtube.com/redhatlatam>
>
>

Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Pete Muir

On 7 Aug 2014, at 18:47, Rafael Benevides <[hidden email]> wrote:

> Before we have a deal with Michelle's team about these content changes, I think we should close the two other definitions:
>
> - docs location: move to deltaspike sources, create a new repository, other?

+1 to move to sources

> and
> -docs format: markdown or asciidoc

+1 for asciidoc.

However I believe we also need agree on:

* add support for asciidoc to Apache CMS
* add support for importing external repo to Apache CMS

so that the docs can still be build as part of the website.

From what people have said in the past, both are possible, if someone (e.g. Rafael ;-) can spend a couple of days doing it.

>
> I believe that we should propose a vote to decided this, otherwise it can become an endless discussion. Wdyt ?
>
>
>
> Em 8/4/14, 17:28, Gerhard Petracek escreveu:
>> @suggested content changes:
>> +1
>>
>> regards,
>> gerhard
>>
>>
>>
>> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email] <mailto:[hidden email]>>:
>>
>>    Hi all,
>>
>>    As you may known, Red Hat docs team was called to help on
>>    DeltaSpike docs. After a long period, they have analyzed the
>>    documentation and bring us an awesome plan that is available here:
>>    https://docs.google.com/document/d/186f_amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>
>>    The document is opened for comments.
>>
>>    Something that was also discussed not only inside Red Hat but with
>>    some community members is about the format and source of the
>>    documentation. I strongly believe that we should have the
>>    documentation somewhere else but the DS site source. It could
>>    improve the ease to the community to contribute with it. Having
>>    said that, it's also suggested that we should use asciidoc as
>>    documentation format.
>>
>>    So what we have until now ?
>>
>>    - The documentation plan to be reviewed and approved by the DS
>>    community. Then we can talk about the plans to make it happen.
>>    - The documentation location: Recommendation to be out of the site
>>    source.
>>    - The documentation format: Suggested to use asciidoc.
>>
>>    Please, read the plan and lets discuss about these 3 topics
>>    individually.
>>
>>    Michelle Murray (whose team provided the plan and she is copied on
>>    this Thread) can follow the feedback.
>>    --
>>    *Rafael Benevides | Senior Software Engineer*
>>    JBoss Developer
>>    M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>
>>    Red Hat
>>
>>    Better technology. Faster innovation. Powered by community
>>    collaboration.
>>    See how it works at www.redhat.com <http://www.redhat.com/>
>>
>>    LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>    <https://www.youtube.com/redhatlatam>
>>
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Rafael Benevides

Em 8/8/14, 6:49, Pete Muir escreveu:
> On 7 Aug 2014, at 18:47, Rafael Benevides <[hidden email]> wrote:
>
>> Before we have a deal with Michelle's team about these content changes, I think we should close the two other definitions:
>>
>> - docs location: move to deltaspike sources, create a new repository, other?
> +1 to move to sources
+1 to move to sources
>
>> and
>> -docs format: markdown or asciidoc
> +1 for asciidoc.
+1 for asciidoc
>
> However I believe we also need agree on:
>
> * add support for asciidoc to Apache CMS
> * add support for importing external repo to Apache CMS
>
> so that the docs can still be build as part of the website.
>
>  From what people have said in the past, both are possible, if someone (e.g. Rafael ;-) can spend a couple of days doing it.
Definitely I would like to help/handle that. I believe that both
(asciidoc support + importing external repo) will bring open doors to
documentation contribution.

>
>> I believe that we should propose a vote to decided this, otherwise it can become an endless discussion. Wdyt ?
>>
>>
>>
>> Em 8/4/14, 17:28, Gerhard Petracek escreveu:
>>> @suggested content changes:
>>> +1
>>>
>>> regards,
>>> gerhard
>>>
>>>
>>>
>>> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email] <mailto:[hidden email]>>:
>>>
>>>     Hi all,
>>>
>>>     As you may known, Red Hat docs team was called to help on
>>>     DeltaSpike docs. After a long period, they have analyzed the
>>>     documentation and bring us an awesome plan that is available here:
>>>     https://docs.google.com/document/d/186f_amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>>
>>>     The document is opened for comments.
>>>
>>>     Something that was also discussed not only inside Red Hat but with
>>>     some community members is about the format and source of the
>>>     documentation. I strongly believe that we should have the
>>>     documentation somewhere else but the DS site source. It could
>>>     improve the ease to the community to contribute with it. Having
>>>     said that, it's also suggested that we should use asciidoc as
>>>     documentation format.
>>>
>>>     So what we have until now ?
>>>
>>>     - The documentation plan to be reviewed and approved by the DS
>>>     community. Then we can talk about the plans to make it happen.
>>>     - The documentation location: Recommendation to be out of the site
>>>     source.
>>>     - The documentation format: Suggested to use asciidoc.
>>>
>>>     Please, read the plan and lets discuss about these 3 topics
>>>     individually.
>>>
>>>     Michelle Murray (whose team provided the plan and she is copied on
>>>     this Thread) can follow the feedback.
>>>     --
>>>     *Rafael Benevides | Senior Software Engineer*
>>>     JBoss Developer
>>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>
>>>     Red Hat
>>>
>>>     Better technology. Faster innovation. Powered by community
>>>     collaboration.
>>>     See how it works at www.redhat.com <http://www.redhat.com/>
>>>
>>>     LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>>     <https://www.youtube.com/redhatlatam>
>>>
>>>

Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
I think we need to convince infra@ that these are all must needed features.
 From looking at the code behind CMS, it would appear that it's the one
calling markdown based on the imports in our files.  Unless we want to do
something crazy like render asciidoc in markdown format, then hand that
over for rendering..

Still would need to convince that pulling from git over the svn site is
ideal as well.

John


On Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
wrote:

>
> Em 8/8/14, 6:49, Pete Muir escreveu:
>
>  On 7 Aug 2014, at 18:47, Rafael Benevides <[hidden email]> wrote:
>>
>>  Before we have a deal with Michelle's team about these content changes,
>>> I think we should close the two other definitions:
>>>
>>> - docs location: move to deltaspike sources, create a new repository,
>>> other?
>>>
>> +1 to move to sources
>>
> +1 to move to sources
>
>>
>>  and
>>> -docs format: markdown or asciidoc
>>>
>> +1 for asciidoc.
>>
> +1 for asciidoc
>
>
>> However I believe we also need agree on:
>>
>> * add support for asciidoc to Apache CMS
>> * add support for importing external repo to Apache CMS
>>
>> so that the docs can still be build as part of the website.
>>
>>  From what people have said in the past, both are possible, if someone
>> (e.g. Rafael ;-) can spend a couple of days doing it.
>>
> Definitely I would like to help/handle that. I believe that both (asciidoc
> support + importing external repo) will bring open doors to documentation
> contribution.
>
>
>>  I believe that we should propose a vote to decided this, otherwise it
>>> can become an endless discussion. Wdyt ?
>>>
>>>
>>>
>>> Em 8/4/14, 17:28, Gerhard Petracek escreveu:
>>>
>>>> @suggested content changes:
>>>> +1
>>>>
>>>> regards,
>>>> gerhard
>>>>
>>>>
>>>>
>>>> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email]
>>>> <mailto:[hidden email]>>:
>>>>
>>>>     Hi all,
>>>>
>>>>     As you may known, Red Hat docs team was called to help on
>>>>     DeltaSpike docs. After a long period, they have analyzed the
>>>>     documentation and bring us an awesome plan that is available here:
>>>>     https://docs.google.com/document/d/186f_
>>>> amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>>>
>>>>     The document is opened for comments.
>>>>
>>>>     Something that was also discussed not only inside Red Hat but with
>>>>     some community members is about the format and source of the
>>>>     documentation. I strongly believe that we should have the
>>>>     documentation somewhere else but the DS site source. It could
>>>>     improve the ease to the community to contribute with it. Having
>>>>     said that, it's also suggested that we should use asciidoc as
>>>>     documentation format.
>>>>
>>>>     So what we have until now ?
>>>>
>>>>     - The documentation plan to be reviewed and approved by the DS
>>>>     community. Then we can talk about the plans to make it happen.
>>>>     - The documentation location: Recommendation to be out of the site
>>>>     source.
>>>>     - The documentation format: Suggested to use asciidoc.
>>>>
>>>>     Please, read the plan and lets discuss about these 3 topics
>>>>     individually.
>>>>
>>>>     Michelle Murray (whose team provided the plan and she is copied on
>>>>     this Thread) can follow the feedback.
>>>>     --
>>>>     *Rafael Benevides | Senior Software Engineer*
>>>>     JBoss Developer
>>>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>>
>>>>     Red Hat
>>>>
>>>>     Better technology. Faster innovation. Powered by community
>>>>     collaboration.
>>>>     See how it works at www.redhat.com <http://www.redhat.com/>
>>>>
>>>>     LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>>>     <https://www.youtube.com/redhatlatam>
>>>>
>>>>
>>>>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Gerhard Petracek
Administrator
@john:
the infra team is usually not the blocking part (if there is no significant
technical issue and they don't get a new heavy part to maintain).

regards,
gerhard



2014-08-08 15:37 GMT+02:00 John D. Ament <[hidden email]>:

> I think we need to convince infra@ that these are all must needed
> features.
>  From looking at the code behind CMS, it would appear that it's the one
> calling markdown based on the imports in our files.  Unless we want to do
> something crazy like render asciidoc in markdown format, then hand that
> over for rendering..
>
> Still would need to convince that pulling from git over the svn site is
> ideal as well.
>
> John
>
>
> On Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
> wrote:
>
> >
> > Em 8/8/14, 6:49, Pete Muir escreveu:
> >
> >  On 7 Aug 2014, at 18:47, Rafael Benevides <[hidden email]> wrote:
> >>
> >>  Before we have a deal with Michelle's team about these content changes,
> >>> I think we should close the two other definitions:
> >>>
> >>> - docs location: move to deltaspike sources, create a new repository,
> >>> other?
> >>>
> >> +1 to move to sources
> >>
> > +1 to move to sources
> >
> >>
> >>  and
> >>> -docs format: markdown or asciidoc
> >>>
> >> +1 for asciidoc.
> >>
> > +1 for asciidoc
> >
> >
> >> However I believe we also need agree on:
> >>
> >> * add support for asciidoc to Apache CMS
> >> * add support for importing external repo to Apache CMS
> >>
> >> so that the docs can still be build as part of the website.
> >>
> >>  From what people have said in the past, both are possible, if someone
> >> (e.g. Rafael ;-) can spend a couple of days doing it.
> >>
> > Definitely I would like to help/handle that. I believe that both
> (asciidoc
> > support + importing external repo) will bring open doors to documentation
> > contribution.
> >
> >
> >>  I believe that we should propose a vote to decided this, otherwise it
> >>> can become an endless discussion. Wdyt ?
> >>>
> >>>
> >>>
> >>> Em 8/4/14, 17:28, Gerhard Petracek escreveu:
> >>>
> >>>> @suggested content changes:
> >>>> +1
> >>>>
> >>>> regards,
> >>>> gerhard
> >>>>
> >>>>
> >>>>
> >>>> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email]
> >>>> <mailto:[hidden email]>>:
> >>>>
> >>>>     Hi all,
> >>>>
> >>>>     As you may known, Red Hat docs team was called to help on
> >>>>     DeltaSpike docs. After a long period, they have analyzed the
> >>>>     documentation and bring us an awesome plan that is available here:
> >>>>     https://docs.google.com/document/d/186f_
> >>>> amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
> >>>>
> >>>>     The document is opened for comments.
> >>>>
> >>>>     Something that was also discussed not only inside Red Hat but with
> >>>>     some community members is about the format and source of the
> >>>>     documentation. I strongly believe that we should have the
> >>>>     documentation somewhere else but the DS site source. It could
> >>>>     improve the ease to the community to contribute with it. Having
> >>>>     said that, it's also suggested that we should use asciidoc as
> >>>>     documentation format.
> >>>>
> >>>>     So what we have until now ?
> >>>>
> >>>>     - The documentation plan to be reviewed and approved by the DS
> >>>>     community. Then we can talk about the plans to make it happen.
> >>>>     - The documentation location: Recommendation to be out of the site
> >>>>     source.
> >>>>     - The documentation format: Suggested to use asciidoc.
> >>>>
> >>>>     Please, read the plan and lets discuss about these 3 topics
> >>>>     individually.
> >>>>
> >>>>     Michelle Murray (whose team provided the plan and she is copied on
> >>>>     this Thread) can follow the feedback.
> >>>>     --
> >>>>     *Rafael Benevides | Senior Software Engineer*
> >>>>     JBoss Developer
> >>>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
> >>>>
> >>>>     Red Hat
> >>>>
> >>>>     Better technology. Faster innovation. Powered by community
> >>>>     collaboration.
> >>>>     See how it works at www.redhat.com <http://www.redhat.com/>
> >>>>
> >>>>     LinkedIn <http://www.linkedin.com/company/3258288> Youtube
> >>>>     <https://www.youtube.com/redhatlatam>
> >>>>
> >>>>
> >>>>
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Rafael Benevides
I remember that someone said that CMS already supports remote
repositories. Can't we start by having this documents moved soon while
we discuss about the asciidoc rendering ?

Em 8/8/14, 10:53, Gerhard Petracek escreveu:

> @john:
> the infra team is usually not the blocking part (if there is no significant
> technical issue and they don't get a new heavy part to maintain).
>
> regards,
> gerhard
>
>
>
> 2014-08-08 15:37 GMT+02:00 John D. Ament <[hidden email]>:
>
>> I think we need to convince infra@ that these are all must needed
>> features.
>>   From looking at the code behind CMS, it would appear that it's the one
>> calling markdown based on the imports in our files.  Unless we want to do
>> something crazy like render asciidoc in markdown format, then hand that
>> over for rendering..
>>
>> Still would need to convince that pulling from git over the svn site is
>> ideal as well.
>>
>> John
>>
>>
>> On Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
>> wrote:
>>
>>> Em 8/8/14, 6:49, Pete Muir escreveu:
>>>
>>>   On 7 Aug 2014, at 18:47, Rafael Benevides <[hidden email]> wrote:
>>>>   Before we have a deal with Michelle's team about these content changes,
>>>>> I think we should close the two other definitions:
>>>>>
>>>>> - docs location: move to deltaspike sources, create a new repository,
>>>>> other?
>>>>>
>>>> +1 to move to sources
>>>>
>>> +1 to move to sources
>>>
>>>>   and
>>>>> -docs format: markdown or asciidoc
>>>>>
>>>> +1 for asciidoc.
>>>>
>>> +1 for asciidoc
>>>
>>>
>>>> However I believe we also need agree on:
>>>>
>>>> * add support for asciidoc to Apache CMS
>>>> * add support for importing external repo to Apache CMS
>>>>
>>>> so that the docs can still be build as part of the website.
>>>>
>>>>   From what people have said in the past, both are possible, if someone
>>>> (e.g. Rafael ;-) can spend a couple of days doing it.
>>>>
>>> Definitely I would like to help/handle that. I believe that both
>> (asciidoc
>>> support + importing external repo) will bring open doors to documentation
>>> contribution.
>>>
>>>
>>>>   I believe that we should propose a vote to decided this, otherwise it
>>>>> can become an endless discussion. Wdyt ?
>>>>>
>>>>>
>>>>>
>>>>> Em 8/4/14, 17:28, Gerhard Petracek escreveu:
>>>>>
>>>>>> @suggested content changes:
>>>>>> +1
>>>>>>
>>>>>> regards,
>>>>>> gerhard
>>>>>>
>>>>>>
>>>>>>
>>>>>> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email]
>>>>>> <mailto:[hidden email]>>:
>>>>>>
>>>>>>      Hi all,
>>>>>>
>>>>>>      As you may known, Red Hat docs team was called to help on
>>>>>>      DeltaSpike docs. After a long period, they have analyzed the
>>>>>>      documentation and bring us an awesome plan that is available here:
>>>>>>      https://docs.google.com/document/d/186f_
>>>>>> amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>>>>>
>>>>>>      The document is opened for comments.
>>>>>>
>>>>>>      Something that was also discussed not only inside Red Hat but with
>>>>>>      some community members is about the format and source of the
>>>>>>      documentation. I strongly believe that we should have the
>>>>>>      documentation somewhere else but the DS site source. It could
>>>>>>      improve the ease to the community to contribute with it. Having
>>>>>>      said that, it's also suggested that we should use asciidoc as
>>>>>>      documentation format.
>>>>>>
>>>>>>      So what we have until now ?
>>>>>>
>>>>>>      - The documentation plan to be reviewed and approved by the DS
>>>>>>      community. Then we can talk about the plans to make it happen.
>>>>>>      - The documentation location: Recommendation to be out of the site
>>>>>>      source.
>>>>>>      - The documentation format: Suggested to use asciidoc.
>>>>>>
>>>>>>      Please, read the plan and lets discuss about these 3 topics
>>>>>>      individually.
>>>>>>
>>>>>>      Michelle Murray (whose team provided the plan and she is copied on
>>>>>>      this Thread) can follow the feedback.
>>>>>>      --
>>>>>>      *Rafael Benevides | Senior Software Engineer*
>>>>>>      JBoss Developer
>>>>>>      M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>>>>
>>>>>>      Red Hat
>>>>>>
>>>>>>      Better technology. Faster innovation. Powered by community
>>>>>>      collaboration.
>>>>>>      See how it works at www.redhat.com <http://www.redhat.com/>
>>>>>>
>>>>>>      LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>>>>>      <https://www.youtube.com/redhatlatam>
>>>>>>
>>>>>>
>>>>>>

Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
Actually, from digging around their code, might have an easier solution, so
long as everyone agrees.

I have a small POC setup here:
https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb

I setup a local VM w/ a SVN repo to test it out.  Basically, we can
generate the asciidoc locally using mvn site, then run mvn site-deploy to
move the rendered files to staging.  Once done, login to CMS and promote to
prod.

The only change would be to get infra to switch our script to use the shell
option.  It does put the rendering process on whoever is writing the docs,
but since it's using the java plugin and jruby, nothing should need to be
downloaded separately to machines.


On Fri, Aug 8, 2014 at 1:55 PM, Rafael Benevides <[hidden email]>
wrote:

> I remember that someone said that CMS already supports remote
> repositories. Can't we start by having this documents moved soon while we
> discuss about the asciidoc rendering ?
>
> Em 8/8/14, 10:53, Gerhard Petracek escreveu:
>
>  @john:
>> the infra team is usually not the blocking part (if there is no
>> significant
>> technical issue and they don't get a new heavy part to maintain).
>>
>> regards,
>> gerhard
>>
>>
>>
>> 2014-08-08 15:37 GMT+02:00 John D. Ament <[hidden email]>:
>>
>>  I think we need to convince infra@ that these are all must needed
>>> features.
>>>   From looking at the code behind CMS, it would appear that it's the one
>>> calling markdown based on the imports in our files.  Unless we want to do
>>> something crazy like render asciidoc in markdown format, then hand that
>>> over for rendering..
>>>
>>> Still would need to convince that pulling from git over the svn site is
>>> ideal as well.
>>>
>>> John
>>>
>>>
>>> On Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
>>> wrote:
>>>
>>>  Em 8/8/14, 6:49, Pete Muir escreveu:
>>>>
>>>>   On 7 Aug 2014, at 18:47, Rafael Benevides <[hidden email]>
>>>> wrote:
>>>>
>>>>>   Before we have a deal with Michelle's team about these content
>>>>> changes,
>>>>>
>>>>>> I think we should close the two other definitions:
>>>>>>
>>>>>> - docs location: move to deltaspike sources, create a new repository,
>>>>>> other?
>>>>>>
>>>>>>  +1 to move to sources
>>>>>
>>>>>  +1 to move to sources
>>>>
>>>>    and
>>>>>
>>>>>> -docs format: markdown or asciidoc
>>>>>>
>>>>>>  +1 for asciidoc.
>>>>>
>>>>>  +1 for asciidoc
>>>>
>>>>
>>>>  However I believe we also need agree on:
>>>>>
>>>>> * add support for asciidoc to Apache CMS
>>>>> * add support for importing external repo to Apache CMS
>>>>>
>>>>> so that the docs can still be build as part of the website.
>>>>>
>>>>>   From what people have said in the past, both are possible, if someone
>>>>> (e.g. Rafael ;-) can spend a couple of days doing it.
>>>>>
>>>>>  Definitely I would like to help/handle that. I believe that both
>>>>
>>> (asciidoc
>>>
>>>> support + importing external repo) will bring open doors to
>>>> documentation
>>>> contribution.
>>>>
>>>>
>>>>    I believe that we should propose a vote to decided this, otherwise it
>>>>>
>>>>>> can become an endless discussion. Wdyt ?
>>>>>>
>>>>>>
>>>>>>
>>>>>> Em 8/4/14, 17:28, Gerhard Petracek escreveu:
>>>>>>
>>>>>>  @suggested content changes:
>>>>>>> +1
>>>>>>>
>>>>>>> regards,
>>>>>>> gerhard
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> 2014-08-01 18:46 GMT+02:00 Rafael Benevides <[hidden email]
>>>>>>> <mailto:[hidden email]>>:
>>>>>>>
>>>>>>>      Hi all,
>>>>>>>
>>>>>>>      As you may known, Red Hat docs team was called to help on
>>>>>>>      DeltaSpike docs. After a long period, they have analyzed the
>>>>>>>      documentation and bring us an awesome plan that is available
>>>>>>> here:
>>>>>>>      https://docs.google.com/document/d/186f_
>>>>>>> amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>>>>>>
>>>>>>>      The document is opened for comments.
>>>>>>>
>>>>>>>      Something that was also discussed not only inside Red Hat but
>>>>>>> with
>>>>>>>      some community members is about the format and source of the
>>>>>>>      documentation. I strongly believe that we should have the
>>>>>>>      documentation somewhere else but the DS site source. It could
>>>>>>>      improve the ease to the community to contribute with it. Having
>>>>>>>      said that, it's also suggested that we should use asciidoc as
>>>>>>>      documentation format.
>>>>>>>
>>>>>>>      So what we have until now ?
>>>>>>>
>>>>>>>      - The documentation plan to be reviewed and approved by the DS
>>>>>>>      community. Then we can talk about the plans to make it happen.
>>>>>>>      - The documentation location: Recommendation to be out of the
>>>>>>> site
>>>>>>>      source.
>>>>>>>      - The documentation format: Suggested to use asciidoc.
>>>>>>>
>>>>>>>      Please, read the plan and lets discuss about these 3 topics
>>>>>>>      individually.
>>>>>>>
>>>>>>>      Michelle Murray (whose team provided the plan and she is copied
>>>>>>> on
>>>>>>>      this Thread) can follow the feedback.
>>>>>>>      --
>>>>>>>      *Rafael Benevides | Senior Software Engineer*
>>>>>>>      JBoss Developer
>>>>>>>      M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>>>>>
>>>>>>>      Red Hat
>>>>>>>
>>>>>>>      Better technology. Faster innovation. Powered by community
>>>>>>>      collaboration.
>>>>>>>      See how it works at www.redhat.com <http://www.redhat.com/>
>>>>>>>
>>>>>>>      LinkedIn <http://www.linkedin.com/company/3258288> Youtube
>>>>>>>      <https://www.youtube.com/redhatlatam>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Mark Struberg
Administrator
You can look at batchee.

Romain configured offline doc (with markdown, but could also be asciidoc) and mvn scm-publish

LieGrue,
strub


--------------------------------------------
On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:

 Subject: Re: DeltaSpike docs plan
 To: "deltaspike" <[hidden email]>
 Date: Saturday, 9 August, 2014, 15:54
 
 Actually, from digging
 around their code, might have an easier solution, so
 long as everyone agrees.
 
 I have a small POC setup here:
 https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
 
 I setup a local VM w/ a SVN
 repo to test it out.  Basically, we can
 generate the asciidoc locally using mvn site,
 then run mvn site-deploy to
 move the
 rendered files to staging.  Once done, login to CMS and
 promote to
 prod.
 
 The only change would be to get infra to switch
 our script to use the shell
 option.  It
 does put the rendering process on whoever is writing the
 docs,
 but since it's using the java
 plugin and jruby, nothing should need to be
 downloaded separately to machines.
 
 
 On Fri, Aug 8, 2014 at 1:55
 PM, Rafael Benevides <[hidden email]>
 wrote:
 
 > I
 remember that someone said that CMS already supports
 remote
 > repositories. Can't we start
 by having this documents moved soon while we
 > discuss about the asciidoc rendering ?
 >
 > Em 8/8/14, 10:53,
 Gerhard Petracek escreveu:
 >
 >  @john:
 >> the
 infra team is usually not the blocking part (if there is
 no
 >> significant
 >> technical issue and they don't get
 a new heavy part to maintain).
 >>
 >> regards,
 >>
 gerhard
 >>
 >>
 >>
 >> 2014-08-08
 15:37 GMT+02:00 John D. Ament <[hidden email]>:
 >>
 >>  I think we
 need to convince infra@ that these are all must needed
 >>> features.
 >>>   From looking at the
 code behind CMS, it would appear that it's the one
 >>> calling markdown based on the
 imports in our files.  Unless we want to do
 >>> something crazy like render
 asciidoc in markdown format, then hand that
 >>> over for rendering..
 >>>
 >>> Still
 would need to convince that pulling from git over the svn
 site is
 >>> ideal as well.
 >>>
 >>>
 John
 >>>
 >>>
 >>> On
 Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
 >>> wrote:
 >>>
 >>>  Em
 8/8/14, 6:49, Pete Muir escreveu:
 >>>>
 >>>>   On 7 Aug 2014, at
 18:47, Rafael Benevides <[hidden email]>
 >>>> wrote:
 >>>>
 >>>>>   Before we
 have a deal with Michelle's team about these content
 >>>>> changes,
 >>>>>
 >>>>>> I think we should
 close the two other definitions:
 >>>>>>
 >>>>>> - docs location: move
 to deltaspike sources, create a new repository,
 >>>>>> other?
 >>>>>>
 >>>>>>  +1 to move to
 sources
 >>>>>
 >>>>>  +1 to move to sources
 >>>>
 >>>>    and
 >>>>>
 >>>>>> -docs format: markdown
 or asciidoc
 >>>>>>
 >>>>>>  +1 for asciidoc.
 >>>>>
 >>>>>  +1 for asciidoc
 >>>>
 >>>>
 >>>>  However I believe we also
 need agree on:
 >>>>>
 >>>>> * add support for asciidoc
 to Apache CMS
 >>>>> * add
 support for importing external repo to Apache CMS
 >>>>>
 >>>>> so that the docs can still
 be build as part of the website.
 >>>>>
 >>>>>   From what
 people have said in the past, both are possible, if
 someone
 >>>>> (e.g. Rafael
 ;-) can spend a couple of days doing it.
 >>>>>
 >>>>>  Definitely I would like
 to help/handle that. I believe that both
 >>>>
 >>>
 (asciidoc
 >>>
 >>>> support + importing external
 repo) will bring open doors to
 >>>> documentation
 >>>> contribution.
 >>>>
 >>>>
 >>>>    I believe that we should
 propose a vote to decided this, otherwise it
 >>>>>
 >>>>>> can become an endless
 discussion. Wdyt ?
 >>>>>>
 >>>>>>
 >>>>>>
 >>>>>> Em 8/4/14, 17:28,
 Gerhard Petracek escreveu:
 >>>>>>
 >>>>>>  @suggested content
 changes:
 >>>>>>> +1
 >>>>>>>
 >>>>>>> regards,
 >>>>>>> gerhard
 >>>>>>>
 >>>>>>>
 >>>>>>>
 >>>>>>> 2014-08-01 18:46
 GMT+02:00 Rafael Benevides <[hidden email]
 >>>>>>> <mailto:[hidden email]>>:
 >>>>>>>
 >>>>>>>      Hi all,
 >>>>>>>
 >>>>>>>      As you may
 known, Red Hat docs team was called to help on
 >>>>>>>      DeltaSpike
 docs. After a long period, they have analyzed the
 >>>>>>>     
 documentation and bring us an awesome plan that is
 available
 >>>>>>>
 here:
 >>>>>>>     
 https://docs.google.com/document/d/186f_
 >>>>>>>
 amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
 >>>>>>>
 >>>>>>>      The
 document is opened for comments.
 >>>>>>>
 >>>>>>>      Something
 that was also discussed not only inside Red Hat but
 >>>>>>> with
 >>>>>>>      some
 community members is about the format and source of the
 >>>>>>>     
 documentation. I strongly believe that we should have the
 >>>>>>>     
 documentation somewhere else but the DS site source. It
 could
 >>>>>>>     
 improve the ease to the community to contribute with it.
 Having
 >>>>>>>     
 said that, it's also suggested that we should use
 asciidoc as
 >>>>>>> 
     documentation format.
 >>>>>>>
 >>>>>>>      So what we
 have until now ?
 >>>>>>>
 >>>>>>>      - The
 documentation plan to be reviewed and approved by the DS
 >>>>>>>      community.
 Then we can talk about the plans to make it happen.
 >>>>>>>      - The
 documentation location: Recommendation to be out of the
 >>>>>>> site
 >>>>>>>      source.
 >>>>>>>      - The
 documentation format: Suggested to use asciidoc.
 >>>>>>>
 >>>>>>>      Please,
 read the plan and lets discuss about these 3 topics
 >>>>>>>     
 individually.
 >>>>>>>
 >>>>>>>      Michelle
 Murray (whose team provided the plan and she is copied
 >>>>>>> on
 >>>>>>>      this
 Thread) can follow the feedback.
 >>>>>>>      --
 >>>>>>>      *Rafael
 Benevides | Senior Software Engineer*
 >>>>>>>      JBoss
 Developer
 >>>>>>>   
   M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
 >>>>>>>
 >>>>>>>      Red Hat
 >>>>>>>
 >>>>>>>      Better
 technology. Faster innovation. Powered by community
 >>>>>>>     
 collaboration.
 >>>>>>>      See how it
 works at www.redhat.com <http://www.redhat.com/>
 >>>>>>>
 >>>>>>>      LinkedIn
 <http://www.linkedin.com/company/3258288>
 Youtube
 >>>>>>>     
 <https://www.youtube.com/redhatlatam>
 >>>>>>>
 >>>>>>>
 >>>>>>>
 >>>>>>>
 >

Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
@mark

That's what I based it on actually.


On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]> wrote:

> You can look at batchee.
>
> Romain configured offline doc (with markdown, but could also be asciidoc)
> and mvn scm-publish
>
> LieGrue,
> strub
>
>
> --------------------------------------------
> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
>
>  Subject: Re: DeltaSpike docs plan
>  To: "deltaspike" <[hidden email]>
>  Date: Saturday, 9 August, 2014, 15:54
>
>  Actually, from digging
>  around their code, might have an easier solution, so
>  long as everyone agrees.
>
>  I have a small POC setup here:
>
> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
>
>  I setup a local VM w/ a SVN
>  repo to test it out.  Basically, we can
>  generate the asciidoc locally using mvn site,
>  then run mvn site-deploy to
>  move the
>  rendered files to staging.  Once done, login to CMS and
>  promote to
>  prod.
>
>  The only change would be to get infra to switch
>  our script to use the shell
>  option.  It
>  does put the rendering process on whoever is writing the
>  docs,
>  but since it's using the java
>  plugin and jruby, nothing should need to be
>  downloaded separately to machines.
>
>
>  On Fri, Aug 8, 2014 at 1:55
>  PM, Rafael Benevides <[hidden email]>
>  wrote:
>
>  > I
>  remember that someone said that CMS already supports
>  remote
>  > repositories. Can't we start
>  by having this documents moved soon while we
>  > discuss about the asciidoc rendering ?
>  >
>  > Em 8/8/14, 10:53,
>  Gerhard Petracek escreveu:
>  >
>  >  @john:
>  >> the
>  infra team is usually not the blocking part (if there is
>  no
>  >> significant
>  >> technical issue and they don't get
>  a new heavy part to maintain).
>  >>
>  >> regards,
>  >>
>  gerhard
>  >>
>  >>
>  >>
>  >> 2014-08-08
>  15:37 GMT+02:00 John D. Ament <[hidden email]>:
>  >>
>  >>  I think we
>  need to convince infra@ that these are all must needed
>  >>> features.
>  >>>   From looking at the
>  code behind CMS, it would appear that it's the one
>  >>> calling markdown based on the
>  imports in our files.  Unless we want to do
>  >>> something crazy like render
>  asciidoc in markdown format, then hand that
>  >>> over for rendering..
>  >>>
>  >>> Still
>  would need to convince that pulling from git over the svn
>  site is
>  >>> ideal as well.
>  >>>
>  >>>
>  John
>  >>>
>  >>>
>  >>> On
>  Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
>  >>> wrote:
>  >>>
>  >>>  Em
>  8/8/14, 6:49, Pete Muir escreveu:
>  >>>>
>  >>>>   On 7 Aug 2014, at
>  18:47, Rafael Benevides <[hidden email]>
>  >>>> wrote:
>  >>>>
>  >>>>>   Before we
>  have a deal with Michelle's team about these content
>  >>>>> changes,
>  >>>>>
>  >>>>>> I think we should
>  close the two other definitions:
>  >>>>>>
>  >>>>>> - docs location: move
>  to deltaspike sources, create a new repository,
>  >>>>>> other?
>  >>>>>>
>  >>>>>>  +1 to move to
>  sources
>  >>>>>
>  >>>>>  +1 to move to sources
>  >>>>
>  >>>>    and
>  >>>>>
>  >>>>>> -docs format: markdown
>  or asciidoc
>  >>>>>>
>  >>>>>>  +1 for asciidoc.
>  >>>>>
>  >>>>>  +1 for asciidoc
>  >>>>
>  >>>>
>  >>>>  However I believe we also
>  need agree on:
>  >>>>>
>  >>>>> * add support for asciidoc
>  to Apache CMS
>  >>>>> * add
>  support for importing external repo to Apache CMS
>  >>>>>
>  >>>>> so that the docs can still
>  be build as part of the website.
>  >>>>>
>  >>>>>   From what
>  people have said in the past, both are possible, if
>  someone
>  >>>>> (e.g. Rafael
>  ;-) can spend a couple of days doing it.
>  >>>>>
>  >>>>>  Definitely I would like
>  to help/handle that. I believe that both
>  >>>>
>  >>>
>  (asciidoc
>  >>>
>  >>>> support + importing external
>  repo) will bring open doors to
>  >>>> documentation
>  >>>> contribution.
>  >>>>
>  >>>>
>  >>>>    I believe that we should
>  propose a vote to decided this, otherwise it
>  >>>>>
>  >>>>>> can become an endless
>  discussion. Wdyt ?
>  >>>>>>
>  >>>>>>
>  >>>>>>
>  >>>>>> Em 8/4/14, 17:28,
>  Gerhard Petracek escreveu:
>  >>>>>>
>  >>>>>>  @suggested content
>  changes:
>  >>>>>>> +1
>  >>>>>>>
>  >>>>>>> regards,
>  >>>>>>> gerhard
>  >>>>>>>
>  >>>>>>>
>  >>>>>>>
>  >>>>>>> 2014-08-01 18:46
>  GMT+02:00 Rafael Benevides <[hidden email]
>  >>>>>>> <mailto:[hidden email]>>:
>  >>>>>>>
>  >>>>>>>      Hi all,
>  >>>>>>>
>  >>>>>>>      As you may
>  known, Red Hat docs team was called to help on
>  >>>>>>>      DeltaSpike
>  docs. After a long period, they have analyzed the
>  >>>>>>>
>  documentation and bring us an awesome plan that is
>  available
>  >>>>>>>
>  here:
>  >>>>>>>
>  https://docs.google.com/document/d/186f_
>  >>>>>>>
>  amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>  >>>>>>>
>  >>>>>>>      The
>  document is opened for comments.
>  >>>>>>>
>  >>>>>>>      Something
>  that was also discussed not only inside Red Hat but
>  >>>>>>> with
>  >>>>>>>      some
>  community members is about the format and source of the
>  >>>>>>>
>  documentation. I strongly believe that we should have the
>  >>>>>>>
>  documentation somewhere else but the DS site source. It
>  could
>  >>>>>>>
>  improve the ease to the community to contribute with it.
>  Having
>  >>>>>>>
>  said that, it's also suggested that we should use
>  asciidoc as
>  >>>>>>>
>      documentation format.
>  >>>>>>>
>  >>>>>>>      So what we
>  have until now ?
>  >>>>>>>
>  >>>>>>>      - The
>  documentation plan to be reviewed and approved by the DS
>  >>>>>>>      community.
>  Then we can talk about the plans to make it happen.
>  >>>>>>>      - The
>  documentation location: Recommendation to be out of the
>  >>>>>>> site
>  >>>>>>>      source.
>  >>>>>>>      - The
>  documentation format: Suggested to use asciidoc.
>  >>>>>>>
>  >>>>>>>      Please,
>  read the plan and lets discuss about these 3 topics
>  >>>>>>>
>  individually.
>  >>>>>>>
>  >>>>>>>      Michelle
>  Murray (whose team provided the plan and she is copied
>  >>>>>>> on
>  >>>>>>>      this
>  Thread) can follow the feedback.
>  >>>>>>>      --
>  >>>>>>>      *Rafael
>  Benevides | Senior Software Engineer*
>  >>>>>>>      JBoss
>  Developer
>  >>>>>>>
>    M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>  >>>>>>>
>  >>>>>>>      Red Hat
>  >>>>>>>
>  >>>>>>>      Better
>  technology. Faster innovation. Powered by community
>  >>>>>>>
>  collaboration.
>  >>>>>>>      See how it
>  works at www.redhat.com <http://www.redhat.com/>
>  >>>>>>>
>  >>>>>>>      LinkedIn
>  <http://www.linkedin.com/company/3258288>
>  Youtube
>  >>>>>>>
>  <https://www.youtube.com/redhatlatam>
>  >>>>>>>
>  >>>>>>>
>  >>>>>>>
>  >>>>>>>
>  >
>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Rafael Benevides
I ran the PoC and I do really thing that it works for DeltaSpike
(considering that there's no restriction on CMS).

Can I give a green sign to Michelle start the docs refactoring (as
planned) using Asciidoctor? I think that she and her team can work on
its own repository and them move it in one big shot once that we have
all requirements setup. Wdyt ?


Em 8/11/14, 8:17, John D. Ament escreveu:

> @mark
>
> That's what I based it on actually.
>
>
> On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]> wrote:
>
>> You can look at batchee.
>>
>> Romain configured offline doc (with markdown, but could also be asciidoc)
>> and mvn scm-publish
>>
>> LieGrue,
>> strub
>>
>>
>> --------------------------------------------
>> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
>>
>>   Subject: Re: DeltaSpike docs plan
>>   To: "deltaspike" <[hidden email]>
>>   Date: Saturday, 9 August, 2014, 15:54
>>
>>   Actually, from digging
>>   around their code, might have an easier solution, so
>>   long as everyone agrees.
>>
>>   I have a small POC setup here:
>>
>> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
>>
>>   I setup a local VM w/ a SVN
>>   repo to test it out.  Basically, we can
>>   generate the asciidoc locally using mvn site,
>>   then run mvn site-deploy to
>>   move the
>>   rendered files to staging.  Once done, login to CMS and
>>   promote to
>>   prod.
>>
>>   The only change would be to get infra to switch
>>   our script to use the shell
>>   option.  It
>>   does put the rendering process on whoever is writing the
>>   docs,
>>   but since it's using the java
>>   plugin and jruby, nothing should need to be
>>   downloaded separately to machines.
>>
>>
>>   On Fri, Aug 8, 2014 at 1:55
>>   PM, Rafael Benevides <[hidden email]>
>>   wrote:
>>
>>   > I
>>   remember that someone said that CMS already supports
>>   remote
>>   > repositories. Can't we start
>>   by having this documents moved soon while we
>>   > discuss about the asciidoc rendering ?
>>   >
>>   > Em 8/8/14, 10:53,
>>   Gerhard Petracek escreveu:
>>   >
>>   >  @john:
>>   >> the
>>   infra team is usually not the blocking part (if there is
>>   no
>>   >> significant
>>   >> technical issue and they don't get
>>   a new heavy part to maintain).
>>   >>
>>   >> regards,
>>   >>
>>   gerhard
>>   >>
>>   >>
>>   >>
>>   >> 2014-08-08
>>   15:37 GMT+02:00 John D. Ament <[hidden email]>:
>>   >>
>>   >>  I think we
>>   need to convince infra@ that these are all must needed
>>   >>> features.
>>   >>>   From looking at the
>>   code behind CMS, it would appear that it's the one
>>   >>> calling markdown based on the
>>   imports in our files.  Unless we want to do
>>   >>> something crazy like render
>>   asciidoc in markdown format, then hand that
>>   >>> over for rendering..
>>   >>>
>>   >>> Still
>>   would need to convince that pulling from git over the svn
>>   site is
>>   >>> ideal as well.
>>   >>>
>>   >>>
>>   John
>>   >>>
>>   >>>
>>   >>> On
>>   Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
>>   >>> wrote:
>>   >>>
>>   >>>  Em
>>   8/8/14, 6:49, Pete Muir escreveu:
>>   >>>>
>>   >>>>   On 7 Aug 2014, at
>>   18:47, Rafael Benevides <[hidden email]>
>>   >>>> wrote:
>>   >>>>
>>   >>>>>   Before we
>>   have a deal with Michelle's team about these content
>>   >>>>> changes,
>>   >>>>>
>>   >>>>>> I think we should
>>   close the two other definitions:
>>   >>>>>>
>>   >>>>>> - docs location: move
>>   to deltaspike sources, create a new repository,
>>   >>>>>> other?
>>   >>>>>>
>>   >>>>>>  +1 to move to
>>   sources
>>   >>>>>
>>   >>>>>  +1 to move to sources
>>   >>>>
>>   >>>>    and
>>   >>>>>
>>   >>>>>> -docs format: markdown
>>   or asciidoc
>>   >>>>>>
>>   >>>>>>  +1 for asciidoc.
>>   >>>>>
>>   >>>>>  +1 for asciidoc
>>   >>>>
>>   >>>>
>>   >>>>  However I believe we also
>>   need agree on:
>>   >>>>>
>>   >>>>> * add support for asciidoc
>>   to Apache CMS
>>   >>>>> * add
>>   support for importing external repo to Apache CMS
>>   >>>>>
>>   >>>>> so that the docs can still
>>   be build as part of the website.
>>   >>>>>
>>   >>>>>   From what
>>   people have said in the past, both are possible, if
>>   someone
>>   >>>>> (e.g. Rafael
>>   ;-) can spend a couple of days doing it.
>>   >>>>>
>>   >>>>>  Definitely I would like
>>   to help/handle that. I believe that both
>>   >>>>
>>   >>>
>>   (asciidoc
>>   >>>
>>   >>>> support + importing external
>>   repo) will bring open doors to
>>   >>>> documentation
>>   >>>> contribution.
>>   >>>>
>>   >>>>
>>   >>>>    I believe that we should
>>   propose a vote to decided this, otherwise it
>>   >>>>>
>>   >>>>>> can become an endless
>>   discussion. Wdyt ?
>>   >>>>>>
>>   >>>>>>
>>   >>>>>>
>>   >>>>>> Em 8/4/14, 17:28,
>>   Gerhard Petracek escreveu:
>>   >>>>>>
>>   >>>>>>  @suggested content
>>   changes:
>>   >>>>>>> +1
>>   >>>>>>>
>>   >>>>>>> regards,
>>   >>>>>>> gerhard
>>   >>>>>>>
>>   >>>>>>>
>>   >>>>>>>
>>   >>>>>>> 2014-08-01 18:46
>>   GMT+02:00 Rafael Benevides <[hidden email]
>>   >>>>>>> <mailto:[hidden email]>>:
>>   >>>>>>>
>>   >>>>>>>      Hi all,
>>   >>>>>>>
>>   >>>>>>>      As you may
>>   known, Red Hat docs team was called to help on
>>   >>>>>>>      DeltaSpike
>>   docs. After a long period, they have analyzed the
>>   >>>>>>>
>>   documentation and bring us an awesome plan that is
>>   available
>>   >>>>>>>
>>   here:
>>   >>>>>>>
>>   https://docs.google.com/document/d/186f_
>>   >>>>>>>
>>   amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>   >>>>>>>
>>   >>>>>>>      The
>>   document is opened for comments.
>>   >>>>>>>
>>   >>>>>>>      Something
>>   that was also discussed not only inside Red Hat but
>>   >>>>>>> with
>>   >>>>>>>      some
>>   community members is about the format and source of the
>>   >>>>>>>
>>   documentation. I strongly believe that we should have the
>>   >>>>>>>
>>   documentation somewhere else but the DS site source. It
>>   could
>>   >>>>>>>
>>   improve the ease to the community to contribute with it.
>>   Having
>>   >>>>>>>
>>   said that, it's also suggested that we should use
>>   asciidoc as
>>   >>>>>>>
>>       documentation format.
>>   >>>>>>>
>>   >>>>>>>      So what we
>>   have until now ?
>>   >>>>>>>
>>   >>>>>>>      - The
>>   documentation plan to be reviewed and approved by the DS
>>   >>>>>>>      community.
>>   Then we can talk about the plans to make it happen.
>>   >>>>>>>      - The
>>   documentation location: Recommendation to be out of the
>>   >>>>>>> site
>>   >>>>>>>      source.
>>   >>>>>>>      - The
>>   documentation format: Suggested to use asciidoc.
>>   >>>>>>>
>>   >>>>>>>      Please,
>>   read the plan and lets discuss about these 3 topics
>>   >>>>>>>
>>   individually.
>>   >>>>>>>
>>   >>>>>>>      Michelle
>>   Murray (whose team provided the plan and she is copied
>>   >>>>>>> on
>>   >>>>>>>      this
>>   Thread) can follow the feedback.
>>   >>>>>>>      --
>>   >>>>>>>      *Rafael
>>   Benevides | Senior Software Engineer*
>>   >>>>>>>      JBoss
>>   Developer
>>   >>>>>>>
>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>   >>>>>>>
>>   >>>>>>>      Red Hat
>>   >>>>>>>
>>   >>>>>>>      Better
>>   technology. Faster innovation. Powered by community
>>   >>>>>>>
>>   collaboration.
>>   >>>>>>>      See how it
>>   works at www.redhat.com <http://www.redhat.com/>
>>   >>>>>>>
>>   >>>>>>>      LinkedIn
>>   <http://www.linkedin.com/company/3258288>
>>   Youtube
>>   >>>>>>>
>>   <https://www.youtube.com/redhatlatam>
>>   >>>>>>>
>>   >>>>>>>
>>   >>>>>>>
>>   >>>>>>>
>>   >
>>
>>

Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Jason Porter
+1 from me. —
Sent from Mailbox

On Mon, Aug 11, 2014 at 9:54 AM, Rafael Benevides <[hidden email]>
wrote:

> I ran the PoC and I do really thing that it works for DeltaSpike
> (considering that there's no restriction on CMS).
> Can I give a green sign to Michelle start the docs refactoring (as
> planned) using Asciidoctor? I think that she and her team can work on
> its own repository and them move it in one big shot once that we have
> all requirements setup. Wdyt ?
> Em 8/11/14, 8:17, John D. Ament escreveu:
>> @mark
>>
>> That's what I based it on actually.
>>
>>
>> On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]> wrote:
>>
>>> You can look at batchee.
>>>
>>> Romain configured offline doc (with markdown, but could also be asciidoc)
>>> and mvn scm-publish
>>>
>>> LieGrue,
>>> strub
>>>
>>>
>>> --------------------------------------------
>>> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
>>>
>>>   Subject: Re: DeltaSpike docs plan
>>>   To: "deltaspike" <[hidden email]>
>>>   Date: Saturday, 9 August, 2014, 15:54
>>>
>>>   Actually, from digging
>>>   around their code, might have an easier solution, so
>>>   long as everyone agrees.
>>>
>>>   I have a small POC setup here:
>>>
>>> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
>>>
>>>   I setup a local VM w/ a SVN
>>>   repo to test it out.  Basically, we can
>>>   generate the asciidoc locally using mvn site,
>>>   then run mvn site-deploy to
>>>   move the
>>>   rendered files to staging.  Once done, login to CMS and
>>>   promote to
>>>   prod.
>>>
>>>   The only change would be to get infra to switch
>>>   our script to use the shell
>>>   option.  It
>>>   does put the rendering process on whoever is writing the
>>>   docs,
>>>   but since it's using the java
>>>   plugin and jruby, nothing should need to be
>>>   downloaded separately to machines.
>>>
>>>
>>>   On Fri, Aug 8, 2014 at 1:55
>>>   PM, Rafael Benevides <[hidden email]>
>>>   wrote:
>>>
>>>   > I
>>>   remember that someone said that CMS already supports
>>>   remote
>>>   > repositories. Can't we start
>>>   by having this documents moved soon while we
>>>   > discuss about the asciidoc rendering ?
>>>   >
>>>   > Em 8/8/14, 10:53,
>>>   Gerhard Petracek escreveu:
>>>   >
>>>   >  @john:
>>>   >> the
>>>   infra team is usually not the blocking part (if there is
>>>   no
>>>   >> significant
>>>   >> technical issue and they don't get
>>>   a new heavy part to maintain).
>>>   >>
>>>   >> regards,
>>>   >>
>>>   gerhard
>>>   >>
>>>   >>
>>>   >>
>>>   >> 2014-08-08
>>>   15:37 GMT+02:00 John D. Ament <[hidden email]>:
>>>   >>
>>>   >>  I think we
>>>   need to convince infra@ that these are all must needed
>>>   >>> features.
>>>   >>>   From looking at the
>>>   code behind CMS, it would appear that it's the one
>>>   >>> calling markdown based on the
>>>   imports in our files.  Unless we want to do
>>>   >>> something crazy like render
>>>   asciidoc in markdown format, then hand that
>>>   >>> over for rendering..
>>>   >>>
>>>   >>> Still
>>>   would need to convince that pulling from git over the svn
>>>   site is
>>>   >>> ideal as well.
>>>   >>>
>>>   >>>
>>>   John
>>>   >>>
>>>   >>>
>>>   >>> On
>>>   Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
>>>   >>> wrote:
>>>   >>>
>>>   >>>  Em
>>>   8/8/14, 6:49, Pete Muir escreveu:
>>>   >>>>
>>>   >>>>   On 7 Aug 2014, at
>>>   18:47, Rafael Benevides <[hidden email]>
>>>   >>>> wrote:
>>>   >>>>
>>>   >>>>>   Before we
>>>   have a deal with Michelle's team about these content
>>>   >>>>> changes,
>>>   >>>>>
>>>   >>>>>> I think we should
>>>   close the two other definitions:
>>>   >>>>>>
>>>   >>>>>> - docs location: move
>>>   to deltaspike sources, create a new repository,
>>>   >>>>>> other?
>>>   >>>>>>
>>>   >>>>>>  +1 to move to
>>>   sources
>>>   >>>>>
>>>   >>>>>  +1 to move to sources
>>>   >>>>
>>>   >>>>    and
>>>   >>>>>
>>>   >>>>>> -docs format: markdown
>>>   or asciidoc
>>>   >>>>>>
>>>   >>>>>>  +1 for asciidoc.
>>>   >>>>>
>>>   >>>>>  +1 for asciidoc
>>>   >>>>
>>>   >>>>
>>>   >>>>  However I believe we also
>>>   need agree on:
>>>   >>>>>
>>>   >>>>> * add support for asciidoc
>>>   to Apache CMS
>>>   >>>>> * add
>>>   support for importing external repo to Apache CMS
>>>   >>>>>
>>>   >>>>> so that the docs can still
>>>   be build as part of the website.
>>>   >>>>>
>>>   >>>>>   From what
>>>   people have said in the past, both are possible, if
>>>   someone
>>>   >>>>> (e.g. Rafael
>>>   ;-) can spend a couple of days doing it.
>>>   >>>>>
>>>   >>>>>  Definitely I would like
>>>   to help/handle that. I believe that both
>>>   >>>>
>>>   >>>
>>>   (asciidoc
>>>   >>>
>>>   >>>> support + importing external
>>>   repo) will bring open doors to
>>>   >>>> documentation
>>>   >>>> contribution.
>>>   >>>>
>>>   >>>>
>>>   >>>>    I believe that we should
>>>   propose a vote to decided this, otherwise it
>>>   >>>>>
>>>   >>>>>> can become an endless
>>>   discussion. Wdyt ?
>>>   >>>>>>
>>>   >>>>>>
>>>   >>>>>>
>>>   >>>>>> Em 8/4/14, 17:28,
>>>   Gerhard Petracek escreveu:
>>>   >>>>>>
>>>   >>>>>>  @suggested content
>>>   changes:
>>>   >>>>>>> +1
>>>   >>>>>>>
>>>   >>>>>>> regards,
>>>   >>>>>>> gerhard
>>>   >>>>>>>
>>>   >>>>>>>
>>>   >>>>>>>
>>>   >>>>>>> 2014-08-01 18:46
>>>   GMT+02:00 Rafael Benevides <[hidden email]
>>>   >>>>>>> <mailto:[hidden email]>>:
>>>   >>>>>>>
>>>   >>>>>>>      Hi all,
>>>   >>>>>>>
>>>   >>>>>>>      As you may
>>>   known, Red Hat docs team was called to help on
>>>   >>>>>>>      DeltaSpike
>>>   docs. After a long period, they have analyzed the
>>>   >>>>>>>
>>>   documentation and bring us an awesome plan that is
>>>   available
>>>   >>>>>>>
>>>   here:
>>>   >>>>>>>
>>>   https://docs.google.com/document/d/186f_
>>>   >>>>>>>
>>>   amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>>   >>>>>>>
>>>   >>>>>>>      The
>>>   document is opened for comments.
>>>   >>>>>>>
>>>   >>>>>>>      Something
>>>   that was also discussed not only inside Red Hat but
>>>   >>>>>>> with
>>>   >>>>>>>      some
>>>   community members is about the format and source of the
>>>   >>>>>>>
>>>   documentation. I strongly believe that we should have the
>>>   >>>>>>>
>>>   documentation somewhere else but the DS site source. It
>>>   could
>>>   >>>>>>>
>>>   improve the ease to the community to contribute with it.
>>>   Having
>>>   >>>>>>>
>>>   said that, it's also suggested that we should use
>>>   asciidoc as
>>>   >>>>>>>
>>>       documentation format.
>>>   >>>>>>>
>>>   >>>>>>>      So what we
>>>   have until now ?
>>>   >>>>>>>
>>>   >>>>>>>      - The
>>>   documentation plan to be reviewed and approved by the DS
>>>   >>>>>>>      community.
>>>   Then we can talk about the plans to make it happen.
>>>   >>>>>>>      - The
>>>   documentation location: Recommendation to be out of the
>>>   >>>>>>> site
>>>   >>>>>>>      source.
>>>   >>>>>>>      - The
>>>   documentation format: Suggested to use asciidoc.
>>>   >>>>>>>
>>>   >>>>>>>      Please,
>>>   read the plan and lets discuss about these 3 topics
>>>   >>>>>>>
>>>   individually.
>>>   >>>>>>>
>>>   >>>>>>>      Michelle
>>>   Murray (whose team provided the plan and she is copied
>>>   >>>>>>> on
>>>   >>>>>>>      this
>>>   Thread) can follow the feedback.
>>>   >>>>>>>      --
>>>   >>>>>>>      *Rafael
>>>   Benevides | Senior Software Engineer*
>>>   >>>>>>>      JBoss
>>>   Developer
>>>   >>>>>>>
>>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>   >>>>>>>
>>>   >>>>>>>      Red Hat
>>>   >>>>>>>
>>>   >>>>>>>      Better
>>>   technology. Faster innovation. Powered by community
>>>   >>>>>>>
>>>   collaboration.
>>>   >>>>>>>      See how it
>>>   works at www.redhat.com <http://www.redhat.com/>
>>>   >>>>>>>
>>>   >>>>>>>      LinkedIn
>>>   <http://www.linkedin.com/company/3258288>
>>>   Youtube
>>>   >>>>>>>
>>>   <https://www.youtube.com/redhatlatam>
>>>   >>>>>>>
>>>   >>>>>>>
>>>   >>>>>>>
>>>   >>>>>>>
>>>   >
>>>
>>>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
+1 as well.  I can push this folder in to master after 1.0.2 is release, so
as to not mess up Gerhard.


On Mon, Aug 11, 2014 at 11:56 AM, Jason Porter <[hidden email]>
wrote:

> +1 from me. —
> Sent from Mailbox
>
> On Mon, Aug 11, 2014 at 9:54 AM, Rafael Benevides <[hidden email]>
> wrote:
>
> > I ran the PoC and I do really thing that it works for DeltaSpike
> > (considering that there's no restriction on CMS).
> > Can I give a green sign to Michelle start the docs refactoring (as
> > planned) using Asciidoctor? I think that she and her team can work on
> > its own repository and them move it in one big shot once that we have
> > all requirements setup. Wdyt ?
> > Em 8/11/14, 8:17, John D. Ament escreveu:
> >> @mark
> >>
> >> That's what I based it on actually.
> >>
> >>
> >> On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]>
> wrote:
> >>
> >>> You can look at batchee.
> >>>
> >>> Romain configured offline doc (with markdown, but could also be
> asciidoc)
> >>> and mvn scm-publish
> >>>
> >>> LieGrue,
> >>> strub
> >>>
> >>>
> >>> --------------------------------------------
> >>> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
> >>>
> >>>   Subject: Re: DeltaSpike docs plan
> >>>   To: "deltaspike" <[hidden email]>
> >>>   Date: Saturday, 9 August, 2014, 15:54
> >>>
> >>>   Actually, from digging
> >>>   around their code, might have an easier solution, so
> >>>   long as everyone agrees.
> >>>
> >>>   I have a small POC setup here:
> >>>
> >>>
> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
> >>>
> >>>   I setup a local VM w/ a SVN
> >>>   repo to test it out.  Basically, we can
> >>>   generate the asciidoc locally using mvn site,
> >>>   then run mvn site-deploy to
> >>>   move the
> >>>   rendered files to staging.  Once done, login to CMS and
> >>>   promote to
> >>>   prod.
> >>>
> >>>   The only change would be to get infra to switch
> >>>   our script to use the shell
> >>>   option.  It
> >>>   does put the rendering process on whoever is writing the
> >>>   docs,
> >>>   but since it's using the java
> >>>   plugin and jruby, nothing should need to be
> >>>   downloaded separately to machines.
> >>>
> >>>
> >>>   On Fri, Aug 8, 2014 at 1:55
> >>>   PM, Rafael Benevides <[hidden email]>
> >>>   wrote:
> >>>
> >>>   > I
> >>>   remember that someone said that CMS already supports
> >>>   remote
> >>>   > repositories. Can't we start
> >>>   by having this documents moved soon while we
> >>>   > discuss about the asciidoc rendering ?
> >>>   >
> >>>   > Em 8/8/14, 10:53,
> >>>   Gerhard Petracek escreveu:
> >>>   >
> >>>   >  @john:
> >>>   >> the
> >>>   infra team is usually not the blocking part (if there is
> >>>   no
> >>>   >> significant
> >>>   >> technical issue and they don't get
> >>>   a new heavy part to maintain).
> >>>   >>
> >>>   >> regards,
> >>>   >>
> >>>   gerhard
> >>>   >>
> >>>   >>
> >>>   >>
> >>>   >> 2014-08-08
> >>>   15:37 GMT+02:00 John D. Ament <[hidden email]>:
> >>>   >>
> >>>   >>  I think we
> >>>   need to convince infra@ that these are all must needed
> >>>   >>> features.
> >>>   >>>   From looking at the
> >>>   code behind CMS, it would appear that it's the one
> >>>   >>> calling markdown based on the
> >>>   imports in our files.  Unless we want to do
> >>>   >>> something crazy like render
> >>>   asciidoc in markdown format, then hand that
> >>>   >>> over for rendering..
> >>>   >>>
> >>>   >>> Still
> >>>   would need to convince that pulling from git over the svn
> >>>   site is
> >>>   >>> ideal as well.
> >>>   >>>
> >>>   >>>
> >>>   John
> >>>   >>>
> >>>   >>>
> >>>   >>> On
> >>>   Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]>
> >>>   >>> wrote:
> >>>   >>>
> >>>   >>>  Em
> >>>   8/8/14, 6:49, Pete Muir escreveu:
> >>>   >>>>
> >>>   >>>>   On 7 Aug 2014, at
> >>>   18:47, Rafael Benevides <[hidden email]>
> >>>   >>>> wrote:
> >>>   >>>>
> >>>   >>>>>   Before we
> >>>   have a deal with Michelle's team about these content
> >>>   >>>>> changes,
> >>>   >>>>>
> >>>   >>>>>> I think we should
> >>>   close the two other definitions:
> >>>   >>>>>>
> >>>   >>>>>> - docs location: move
> >>>   to deltaspike sources, create a new repository,
> >>>   >>>>>> other?
> >>>   >>>>>>
> >>>   >>>>>>  +1 to move to
> >>>   sources
> >>>   >>>>>
> >>>   >>>>>  +1 to move to sources
> >>>   >>>>
> >>>   >>>>    and
> >>>   >>>>>
> >>>   >>>>>> -docs format: markdown
> >>>   or asciidoc
> >>>   >>>>>>
> >>>   >>>>>>  +1 for asciidoc.
> >>>   >>>>>
> >>>   >>>>>  +1 for asciidoc
> >>>   >>>>
> >>>   >>>>
> >>>   >>>>  However I believe we also
> >>>   need agree on:
> >>>   >>>>>
> >>>   >>>>> * add support for asciidoc
> >>>   to Apache CMS
> >>>   >>>>> * add
> >>>   support for importing external repo to Apache CMS
> >>>   >>>>>
> >>>   >>>>> so that the docs can still
> >>>   be build as part of the website.
> >>>   >>>>>
> >>>   >>>>>   From what
> >>>   people have said in the past, both are possible, if
> >>>   someone
> >>>   >>>>> (e.g. Rafael
> >>>   ;-) can spend a couple of days doing it.
> >>>   >>>>>
> >>>   >>>>>  Definitely I would like
> >>>   to help/handle that. I believe that both
> >>>   >>>>
> >>>   >>>
> >>>   (asciidoc
> >>>   >>>
> >>>   >>>> support + importing external
> >>>   repo) will bring open doors to
> >>>   >>>> documentation
> >>>   >>>> contribution.
> >>>   >>>>
> >>>   >>>>
> >>>   >>>>    I believe that we should
> >>>   propose a vote to decided this, otherwise it
> >>>   >>>>>
> >>>   >>>>>> can become an endless
> >>>   discussion. Wdyt ?
> >>>   >>>>>>
> >>>   >>>>>>
> >>>   >>>>>>
> >>>   >>>>>> Em 8/4/14, 17:28,
> >>>   Gerhard Petracek escreveu:
> >>>   >>>>>>
> >>>   >>>>>>  @suggested content
> >>>   changes:
> >>>   >>>>>>> +1
> >>>   >>>>>>>
> >>>   >>>>>>> regards,
> >>>   >>>>>>> gerhard
> >>>   >>>>>>>
> >>>   >>>>>>>
> >>>   >>>>>>>
> >>>   >>>>>>> 2014-08-01 18:46
> >>>   GMT+02:00 Rafael Benevides <[hidden email]
> >>>   >>>>>>> <mailto:[hidden email]>>:
> >>>   >>>>>>>
> >>>   >>>>>>>      Hi all,
> >>>   >>>>>>>
> >>>   >>>>>>>      As you may
> >>>   known, Red Hat docs team was called to help on
> >>>   >>>>>>>      DeltaSpike
> >>>   docs. After a long period, they have analyzed the
> >>>   >>>>>>>
> >>>   documentation and bring us an awesome plan that is
> >>>   available
> >>>   >>>>>>>
> >>>   here:
> >>>   >>>>>>>
> >>>   https://docs.google.com/document/d/186f_
> >>>   >>>>>>>
> >>>   amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
> >>>   >>>>>>>
> >>>   >>>>>>>      The
> >>>   document is opened for comments.
> >>>   >>>>>>>
> >>>   >>>>>>>      Something
> >>>   that was also discussed not only inside Red Hat but
> >>>   >>>>>>> with
> >>>   >>>>>>>      some
> >>>   community members is about the format and source of the
> >>>   >>>>>>>
> >>>   documentation. I strongly believe that we should have the
> >>>   >>>>>>>
> >>>   documentation somewhere else but the DS site source. It
> >>>   could
> >>>   >>>>>>>
> >>>   improve the ease to the community to contribute with it.
> >>>   Having
> >>>   >>>>>>>
> >>>   said that, it's also suggested that we should use
> >>>   asciidoc as
> >>>   >>>>>>>
> >>>       documentation format.
> >>>   >>>>>>>
> >>>   >>>>>>>      So what we
> >>>   have until now ?
> >>>   >>>>>>>
> >>>   >>>>>>>      - The
> >>>   documentation plan to be reviewed and approved by the DS
> >>>   >>>>>>>      community.
> >>>   Then we can talk about the plans to make it happen.
> >>>   >>>>>>>      - The
> >>>   documentation location: Recommendation to be out of the
> >>>   >>>>>>> site
> >>>   >>>>>>>      source.
> >>>   >>>>>>>      - The
> >>>   documentation format: Suggested to use asciidoc.
> >>>   >>>>>>>
> >>>   >>>>>>>      Please,
> >>>   read the plan and lets discuss about these 3 topics
> >>>   >>>>>>>
> >>>   individually.
> >>>   >>>>>>>
> >>>   >>>>>>>      Michelle
> >>>   Murray (whose team provided the plan and she is copied
> >>>   >>>>>>> on
> >>>   >>>>>>>      this
> >>>   Thread) can follow the feedback.
> >>>   >>>>>>>      --
> >>>   >>>>>>>      *Rafael
> >>>   Benevides | Senior Software Engineer*
> >>>   >>>>>>>      JBoss
> >>>   Developer
> >>>   >>>>>>>
> >>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
> >>>   >>>>>>>
> >>>   >>>>>>>      Red Hat
> >>>   >>>>>>>
> >>>   >>>>>>>      Better
> >>>   technology. Faster innovation. Powered by community
> >>>   >>>>>>>
> >>>   collaboration.
> >>>   >>>>>>>      See how it
> >>>   works at www.redhat.com <http://www.redhat.com/>
> >>>   >>>>>>>
> >>>   >>>>>>>      LinkedIn
> >>>   <http://www.linkedin.com/company/3258288>
> >>>   Youtube
> >>>   >>>>>>>
> >>>   <https://www.youtube.com/redhatlatam>
> >>>   >>>>>>>
> >>>   >>>>>>>
> >>>   >>>>>>>
> >>>   >>>>>>>
> >>>   >
> >>>
> >>>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
All,

Just wondering, can we consider this a binding vote?  Just want to make
sure I have the right links in place.

John


On Mon, Aug 11, 2014 at 12:04 PM, John D. Ament <[hidden email]>
wrote:

> +1 as well.  I can push this folder in to master after 1.0.2 is release,
> so as to not mess up Gerhard.
>
>
> On Mon, Aug 11, 2014 at 11:56 AM, Jason Porter <[hidden email]>
> wrote:
>
>> +1 from me. —
>> Sent from Mailbox
>>
>> On Mon, Aug 11, 2014 at 9:54 AM, Rafael Benevides <[hidden email]>
>> wrote:
>>
>> > I ran the PoC and I do really thing that it works for DeltaSpike
>> > (considering that there's no restriction on CMS).
>> > Can I give a green sign to Michelle start the docs refactoring (as
>> > planned) using Asciidoctor? I think that she and her team can work on
>> > its own repository and them move it in one big shot once that we have
>> > all requirements setup. Wdyt ?
>> > Em 8/11/14, 8:17, John D. Ament escreveu:
>> >> @mark
>> >>
>> >> That's what I based it on actually.
>> >>
>> >>
>> >> On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]>
>> wrote:
>> >>
>> >>> You can look at batchee.
>> >>>
>> >>> Romain configured offline doc (with markdown, but could also be
>> asciidoc)
>> >>> and mvn scm-publish
>> >>>
>> >>> LieGrue,
>> >>> strub
>> >>>
>> >>>
>> >>> --------------------------------------------
>> >>> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
>> >>>
>> >>>   Subject: Re: DeltaSpike docs plan
>> >>>   To: "deltaspike" <[hidden email]>
>> >>>   Date: Saturday, 9 August, 2014, 15:54
>> >>>
>> >>>   Actually, from digging
>> >>>   around their code, might have an easier solution, so
>> >>>   long as everyone agrees.
>> >>>
>> >>>   I have a small POC setup here:
>> >>>
>> >>>
>> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
>> >>>
>> >>>   I setup a local VM w/ a SVN
>> >>>   repo to test it out.  Basically, we can
>> >>>   generate the asciidoc locally using mvn site,
>> >>>   then run mvn site-deploy to
>> >>>   move the
>> >>>   rendered files to staging.  Once done, login to CMS and
>> >>>   promote to
>> >>>   prod.
>> >>>
>> >>>   The only change would be to get infra to switch
>> >>>   our script to use the shell
>> >>>   option.  It
>> >>>   does put the rendering process on whoever is writing the
>> >>>   docs,
>> >>>   but since it's using the java
>> >>>   plugin and jruby, nothing should need to be
>> >>>   downloaded separately to machines.
>> >>>
>> >>>
>> >>>   On Fri, Aug 8, 2014 at 1:55
>> >>>   PM, Rafael Benevides <[hidden email]>
>> >>>   wrote:
>> >>>
>> >>>   > I
>> >>>   remember that someone said that CMS already supports
>> >>>   remote
>> >>>   > repositories. Can't we start
>> >>>   by having this documents moved soon while we
>> >>>   > discuss about the asciidoc rendering ?
>> >>>   >
>> >>>   > Em 8/8/14, 10:53,
>> >>>   Gerhard Petracek escreveu:
>> >>>   >
>> >>>   >  @john:
>> >>>   >> the
>> >>>   infra team is usually not the blocking part (if there is
>> >>>   no
>> >>>   >> significant
>> >>>   >> technical issue and they don't get
>> >>>   a new heavy part to maintain).
>> >>>   >>
>> >>>   >> regards,
>> >>>   >>
>> >>>   gerhard
>> >>>   >>
>> >>>   >>
>> >>>   >>
>> >>>   >> 2014-08-08
>> >>>   15:37 GMT+02:00 John D. Ament <[hidden email]>:
>> >>>   >>
>> >>>   >>  I think we
>> >>>   need to convince infra@ that these are all must needed
>> >>>   >>> features.
>> >>>   >>>   From looking at the
>> >>>   code behind CMS, it would appear that it's the one
>> >>>   >>> calling markdown based on the
>> >>>   imports in our files.  Unless we want to do
>> >>>   >>> something crazy like render
>> >>>   asciidoc in markdown format, then hand that
>> >>>   >>> over for rendering..
>> >>>   >>>
>> >>>   >>> Still
>> >>>   would need to convince that pulling from git over the svn
>> >>>   site is
>> >>>   >>> ideal as well.
>> >>>   >>>
>> >>>   >>>
>> >>>   John
>> >>>   >>>
>> >>>   >>>
>> >>>   >>> On
>> >>>   Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <[hidden email]
>> >
>> >>>   >>> wrote:
>> >>>   >>>
>> >>>   >>>  Em
>> >>>   8/8/14, 6:49, Pete Muir escreveu:
>> >>>   >>>>
>> >>>   >>>>   On 7 Aug 2014, at
>> >>>   18:47, Rafael Benevides <[hidden email]>
>> >>>   >>>> wrote:
>> >>>   >>>>
>> >>>   >>>>>   Before we
>> >>>   have a deal with Michelle's team about these content
>> >>>   >>>>> changes,
>> >>>   >>>>>
>> >>>   >>>>>> I think we should
>> >>>   close the two other definitions:
>> >>>   >>>>>>
>> >>>   >>>>>> - docs location: move
>> >>>   to deltaspike sources, create a new repository,
>> >>>   >>>>>> other?
>> >>>   >>>>>>
>> >>>   >>>>>>  +1 to move to
>> >>>   sources
>> >>>   >>>>>
>> >>>   >>>>>  +1 to move to sources
>> >>>   >>>>
>> >>>   >>>>    and
>> >>>   >>>>>
>> >>>   >>>>>> -docs format: markdown
>> >>>   or asciidoc
>> >>>   >>>>>>
>> >>>   >>>>>>  +1 for asciidoc.
>> >>>   >>>>>
>> >>>   >>>>>  +1 for asciidoc
>> >>>   >>>>
>> >>>   >>>>
>> >>>   >>>>  However I believe we also
>> >>>   need agree on:
>> >>>   >>>>>
>> >>>   >>>>> * add support for asciidoc
>> >>>   to Apache CMS
>> >>>   >>>>> * add
>> >>>   support for importing external repo to Apache CMS
>> >>>   >>>>>
>> >>>   >>>>> so that the docs can still
>> >>>   be build as part of the website.
>> >>>   >>>>>
>> >>>   >>>>>   From what
>> >>>   people have said in the past, both are possible, if
>> >>>   someone
>> >>>   >>>>> (e.g. Rafael
>> >>>   ;-) can spend a couple of days doing it.
>> >>>   >>>>>
>> >>>   >>>>>  Definitely I would like
>> >>>   to help/handle that. I believe that both
>> >>>   >>>>
>> >>>   >>>
>> >>>   (asciidoc
>> >>>   >>>
>> >>>   >>>> support + importing external
>> >>>   repo) will bring open doors to
>> >>>   >>>> documentation
>> >>>   >>>> contribution.
>> >>>   >>>>
>> >>>   >>>>
>> >>>   >>>>    I believe that we should
>> >>>   propose a vote to decided this, otherwise it
>> >>>   >>>>>
>> >>>   >>>>>> can become an endless
>> >>>   discussion. Wdyt ?
>> >>>   >>>>>>
>> >>>   >>>>>>
>> >>>   >>>>>>
>> >>>   >>>>>> Em 8/4/14, 17:28,
>> >>>   Gerhard Petracek escreveu:
>> >>>   >>>>>>
>> >>>   >>>>>>  @suggested content
>> >>>   changes:
>> >>>   >>>>>>> +1
>> >>>   >>>>>>>
>> >>>   >>>>>>> regards,
>> >>>   >>>>>>> gerhard
>> >>>   >>>>>>>
>> >>>   >>>>>>>
>> >>>   >>>>>>>
>> >>>   >>>>>>> 2014-08-01 18:46
>> >>>   GMT+02:00 Rafael Benevides <[hidden email]
>> >>>   >>>>>>> <mailto:[hidden email]>>:
>> >>>   >>>>>>>
>> >>>   >>>>>>>      Hi all,
>> >>>   >>>>>>>
>> >>>   >>>>>>>      As you may
>> >>>   known, Red Hat docs team was called to help on
>> >>>   >>>>>>>      DeltaSpike
>> >>>   docs. After a long period, they have analyzed the
>> >>>   >>>>>>>
>> >>>   documentation and bring us an awesome plan that is
>> >>>   available
>> >>>   >>>>>>>
>> >>>   here:
>> >>>   >>>>>>>
>> >>>   https://docs.google.com/document/d/186f_
>> >>>   >>>>>>>
>> >>>   amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>> >>>   >>>>>>>
>> >>>   >>>>>>>      The
>> >>>   document is opened for comments.
>> >>>   >>>>>>>
>> >>>   >>>>>>>      Something
>> >>>   that was also discussed not only inside Red Hat but
>> >>>   >>>>>>> with
>> >>>   >>>>>>>      some
>> >>>   community members is about the format and source of the
>> >>>   >>>>>>>
>> >>>   documentation. I strongly believe that we should have the
>> >>>   >>>>>>>
>> >>>   documentation somewhere else but the DS site source. It
>> >>>   could
>> >>>   >>>>>>>
>> >>>   improve the ease to the community to contribute with it.
>> >>>   Having
>> >>>   >>>>>>>
>> >>>   said that, it's also suggested that we should use
>> >>>   asciidoc as
>> >>>   >>>>>>>
>> >>>       documentation format.
>> >>>   >>>>>>>
>> >>>   >>>>>>>      So what we
>> >>>   have until now ?
>> >>>   >>>>>>>
>> >>>   >>>>>>>      - The
>> >>>   documentation plan to be reviewed and approved by the DS
>> >>>   >>>>>>>      community.
>> >>>   Then we can talk about the plans to make it happen.
>> >>>   >>>>>>>      - The
>> >>>   documentation location: Recommendation to be out of the
>> >>>   >>>>>>> site
>> >>>   >>>>>>>      source.
>> >>>   >>>>>>>      - The
>> >>>   documentation format: Suggested to use asciidoc.
>> >>>   >>>>>>>
>> >>>   >>>>>>>      Please,
>> >>>   read the plan and lets discuss about these 3 topics
>> >>>   >>>>>>>
>> >>>   individually.
>> >>>   >>>>>>>
>> >>>   >>>>>>>      Michelle
>> >>>   Murray (whose team provided the plan and she is copied
>> >>>   >>>>>>> on
>> >>>   >>>>>>>      this
>> >>>   Thread) can follow the feedback.
>> >>>   >>>>>>>      --
>> >>>   >>>>>>>      *Rafael
>> >>>   Benevides | Senior Software Engineer*
>> >>>   >>>>>>>      JBoss
>> >>>   Developer
>> >>>   >>>>>>>
>> >>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>> >>>   >>>>>>>
>> >>>   >>>>>>>      Red Hat
>> >>>   >>>>>>>
>> >>>   >>>>>>>      Better
>> >>>   technology. Faster innovation. Powered by community
>> >>>   >>>>>>>
>> >>>   collaboration.
>> >>>   >>>>>>>      See how it
>> >>>   works at www.redhat.com <http://www.redhat.com/>
>> >>>   >>>>>>>
>> >>>   >>>>>>>      LinkedIn
>> >>>   <http://www.linkedin.com/company/3258288>
>> >>>   Youtube
>> >>>   >>>>>>>
>> >>>   <https://www.youtube.com/redhatlatam>
>> >>>   >>>>>>>
>> >>>   >>>>>>>
>> >>>   >>>>>>>
>> >>>   >>>>>>>
>> >>>   >
>> >>>
>> >>>
>>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
Also, I created a JIRA ticket to cover the donation.  All commits related
to the donation should include DELTASPIKE-690 in the commit message, for
tracking purposes, ideally.  The JIRA can be found at [1].

- John

[1]: https://issues.apache.org/jira/browse/DELTASPIKE-690


On Sun, Aug 17, 2014 at 5:26 PM, John D. Ament <[hidden email]>
wrote:

> All,
>
> Just wondering, can we consider this a binding vote?  Just want to make
> sure I have the right links in place.
>
> John
>
>
> On Mon, Aug 11, 2014 at 12:04 PM, John D. Ament <[hidden email]>
> wrote:
>
>> +1 as well.  I can push this folder in to master after 1.0.2 is release,
>> so as to not mess up Gerhard.
>>
>>
>> On Mon, Aug 11, 2014 at 11:56 AM, Jason Porter <[hidden email]>
>> wrote:
>>
>>> +1 from me. —
>>> Sent from Mailbox
>>>
>>> On Mon, Aug 11, 2014 at 9:54 AM, Rafael Benevides <[hidden email]>
>>> wrote:
>>>
>>> > I ran the PoC and I do really thing that it works for DeltaSpike
>>> > (considering that there's no restriction on CMS).
>>> > Can I give a green sign to Michelle start the docs refactoring (as
>>> > planned) using Asciidoctor? I think that she and her team can work on
>>> > its own repository and them move it in one big shot once that we have
>>> > all requirements setup. Wdyt ?
>>> > Em 8/11/14, 8:17, John D. Ament escreveu:
>>> >> @mark
>>> >>
>>> >> That's what I based it on actually.
>>> >>
>>> >>
>>> >> On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]>
>>> wrote:
>>> >>
>>> >>> You can look at batchee.
>>> >>>
>>> >>> Romain configured offline doc (with markdown, but could also be
>>> asciidoc)
>>> >>> and mvn scm-publish
>>> >>>
>>> >>> LieGrue,
>>> >>> strub
>>> >>>
>>> >>>
>>> >>> --------------------------------------------
>>> >>> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
>>> >>>
>>> >>>   Subject: Re: DeltaSpike docs plan
>>> >>>   To: "deltaspike" <[hidden email]>
>>> >>>   Date: Saturday, 9 August, 2014, 15:54
>>> >>>
>>> >>>   Actually, from digging
>>> >>>   around their code, might have an easier solution, so
>>> >>>   long as everyone agrees.
>>> >>>
>>> >>>   I have a small POC setup here:
>>> >>>
>>> >>>
>>> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
>>> >>>
>>> >>>   I setup a local VM w/ a SVN
>>> >>>   repo to test it out.  Basically, we can
>>> >>>   generate the asciidoc locally using mvn site,
>>> >>>   then run mvn site-deploy to
>>> >>>   move the
>>> >>>   rendered files to staging.  Once done, login to CMS and
>>> >>>   promote to
>>> >>>   prod.
>>> >>>
>>> >>>   The only change would be to get infra to switch
>>> >>>   our script to use the shell
>>> >>>   option.  It
>>> >>>   does put the rendering process on whoever is writing the
>>> >>>   docs,
>>> >>>   but since it's using the java
>>> >>>   plugin and jruby, nothing should need to be
>>> >>>   downloaded separately to machines.
>>> >>>
>>> >>>
>>> >>>   On Fri, Aug 8, 2014 at 1:55
>>> >>>   PM, Rafael Benevides <[hidden email]>
>>> >>>   wrote:
>>> >>>
>>> >>>   > I
>>> >>>   remember that someone said that CMS already supports
>>> >>>   remote
>>> >>>   > repositories. Can't we start
>>> >>>   by having this documents moved soon while we
>>> >>>   > discuss about the asciidoc rendering ?
>>> >>>   >
>>> >>>   > Em 8/8/14, 10:53,
>>> >>>   Gerhard Petracek escreveu:
>>> >>>   >
>>> >>>   >  @john:
>>> >>>   >> the
>>> >>>   infra team is usually not the blocking part (if there is
>>> >>>   no
>>> >>>   >> significant
>>> >>>   >> technical issue and they don't get
>>> >>>   a new heavy part to maintain).
>>> >>>   >>
>>> >>>   >> regards,
>>> >>>   >>
>>> >>>   gerhard
>>> >>>   >>
>>> >>>   >>
>>> >>>   >>
>>> >>>   >> 2014-08-08
>>> >>>   15:37 GMT+02:00 John D. Ament <[hidden email]>:
>>> >>>   >>
>>> >>>   >>  I think we
>>> >>>   need to convince infra@ that these are all must needed
>>> >>>   >>> features.
>>> >>>   >>>   From looking at the
>>> >>>   code behind CMS, it would appear that it's the one
>>> >>>   >>> calling markdown based on the
>>> >>>   imports in our files.  Unless we want to do
>>> >>>   >>> something crazy like render
>>> >>>   asciidoc in markdown format, then hand that
>>> >>>   >>> over for rendering..
>>> >>>   >>>
>>> >>>   >>> Still
>>> >>>   would need to convince that pulling from git over the svn
>>> >>>   site is
>>> >>>   >>> ideal as well.
>>> >>>   >>>
>>> >>>   >>>
>>> >>>   John
>>> >>>   >>>
>>> >>>   >>>
>>> >>>   >>> On
>>> >>>   Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <
>>> [hidden email]>
>>> >>>   >>> wrote:
>>> >>>   >>>
>>> >>>   >>>  Em
>>> >>>   8/8/14, 6:49, Pete Muir escreveu:
>>> >>>   >>>>
>>> >>>   >>>>   On 7 Aug 2014, at
>>> >>>   18:47, Rafael Benevides <[hidden email]>
>>> >>>   >>>> wrote:
>>> >>>   >>>>
>>> >>>   >>>>>   Before we
>>> >>>   have a deal with Michelle's team about these content
>>> >>>   >>>>> changes,
>>> >>>   >>>>>
>>> >>>   >>>>>> I think we should
>>> >>>   close the two other definitions:
>>> >>>   >>>>>>
>>> >>>   >>>>>> - docs location: move
>>> >>>   to deltaspike sources, create a new repository,
>>> >>>   >>>>>> other?
>>> >>>   >>>>>>
>>> >>>   >>>>>>  +1 to move to
>>> >>>   sources
>>> >>>   >>>>>
>>> >>>   >>>>>  +1 to move to sources
>>> >>>   >>>>
>>> >>>   >>>>    and
>>> >>>   >>>>>
>>> >>>   >>>>>> -docs format: markdown
>>> >>>   or asciidoc
>>> >>>   >>>>>>
>>> >>>   >>>>>>  +1 for asciidoc.
>>> >>>   >>>>>
>>> >>>   >>>>>  +1 for asciidoc
>>> >>>   >>>>
>>> >>>   >>>>
>>> >>>   >>>>  However I believe we also
>>> >>>   need agree on:
>>> >>>   >>>>>
>>> >>>   >>>>> * add support for asciidoc
>>> >>>   to Apache CMS
>>> >>>   >>>>> * add
>>> >>>   support for importing external repo to Apache CMS
>>> >>>   >>>>>
>>> >>>   >>>>> so that the docs can still
>>> >>>   be build as part of the website.
>>> >>>   >>>>>
>>> >>>   >>>>>   From what
>>> >>>   people have said in the past, both are possible, if
>>> >>>   someone
>>> >>>   >>>>> (e.g. Rafael
>>> >>>   ;-) can spend a couple of days doing it.
>>> >>>   >>>>>
>>> >>>   >>>>>  Definitely I would like
>>> >>>   to help/handle that. I believe that both
>>> >>>   >>>>
>>> >>>   >>>
>>> >>>   (asciidoc
>>> >>>   >>>
>>> >>>   >>>> support + importing external
>>> >>>   repo) will bring open doors to
>>> >>>   >>>> documentation
>>> >>>   >>>> contribution.
>>> >>>   >>>>
>>> >>>   >>>>
>>> >>>   >>>>    I believe that we should
>>> >>>   propose a vote to decided this, otherwise it
>>> >>>   >>>>>
>>> >>>   >>>>>> can become an endless
>>> >>>   discussion. Wdyt ?
>>> >>>   >>>>>>
>>> >>>   >>>>>>
>>> >>>   >>>>>>
>>> >>>   >>>>>> Em 8/4/14, 17:28,
>>> >>>   Gerhard Petracek escreveu:
>>> >>>   >>>>>>
>>> >>>   >>>>>>  @suggested content
>>> >>>   changes:
>>> >>>   >>>>>>> +1
>>> >>>   >>>>>>>
>>> >>>   >>>>>>> regards,
>>> >>>   >>>>>>> gerhard
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>> 2014-08-01 18:46
>>> >>>   GMT+02:00 Rafael Benevides <[hidden email]
>>> >>>   >>>>>>> <mailto:[hidden email]>>:
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      Hi all,
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      As you may
>>> >>>   known, Red Hat docs team was called to help on
>>> >>>   >>>>>>>      DeltaSpike
>>> >>>   docs. After a long period, they have analyzed the
>>> >>>   >>>>>>>
>>> >>>   documentation and bring us an awesome plan that is
>>> >>>   available
>>> >>>   >>>>>>>
>>> >>>   here:
>>> >>>   >>>>>>>
>>> >>>   https://docs.google.com/document/d/186f_
>>> >>>   >>>>>>>
>>> >>>   amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      The
>>> >>>   document is opened for comments.
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      Something
>>> >>>   that was also discussed not only inside Red Hat but
>>> >>>   >>>>>>> with
>>> >>>   >>>>>>>      some
>>> >>>   community members is about the format and source of the
>>> >>>   >>>>>>>
>>> >>>   documentation. I strongly believe that we should have the
>>> >>>   >>>>>>>
>>> >>>   documentation somewhere else but the DS site source. It
>>> >>>   could
>>> >>>   >>>>>>>
>>> >>>   improve the ease to the community to contribute with it.
>>> >>>   Having
>>> >>>   >>>>>>>
>>> >>>   said that, it's also suggested that we should use
>>> >>>   asciidoc as
>>> >>>   >>>>>>>
>>> >>>       documentation format.
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      So what we
>>> >>>   have until now ?
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      - The
>>> >>>   documentation plan to be reviewed and approved by the DS
>>> >>>   >>>>>>>      community.
>>> >>>   Then we can talk about the plans to make it happen.
>>> >>>   >>>>>>>      - The
>>> >>>   documentation location: Recommendation to be out of the
>>> >>>   >>>>>>> site
>>> >>>   >>>>>>>      source.
>>> >>>   >>>>>>>      - The
>>> >>>   documentation format: Suggested to use asciidoc.
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      Please,
>>> >>>   read the plan and lets discuss about these 3 topics
>>> >>>   >>>>>>>
>>> >>>   individually.
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      Michelle
>>> >>>   Murray (whose team provided the plan and she is copied
>>> >>>   >>>>>>> on
>>> >>>   >>>>>>>      this
>>> >>>   Thread) can follow the feedback.
>>> >>>   >>>>>>>      --
>>> >>>   >>>>>>>      *Rafael
>>> >>>   Benevides | Senior Software Engineer*
>>> >>>   >>>>>>>      JBoss
>>> >>>   Developer
>>> >>>   >>>>>>>
>>> >>>     M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      Red Hat
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      Better
>>> >>>   technology. Faster innovation. Powered by community
>>> >>>   >>>>>>>
>>> >>>   collaboration.
>>> >>>   >>>>>>>      See how it
>>> >>>   works at www.redhat.com <http://www.redhat.com/>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>      LinkedIn
>>> >>>   <http://www.linkedin.com/company/3258288>
>>> >>>   Youtube
>>> >>>   >>>>>>>
>>> >>>   <https://www.youtube.com/redhatlatam>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>
>>> >>>   >>>>>>>
>>> >>>   >
>>> >>>
>>> >>>
>>>
>>
>>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Rafael Benevides
Thanks, once more, John,

+1 to consider this a binding vote.

Btw, Do you need any help with CMS?

Em 8/17/14, 18:29, John D. Ament escreveu:

> Also, I created a JIRA ticket to cover the donation.  All commits related
> to the donation should include DELTASPIKE-690 in the commit message, for
> tracking purposes, ideally.  The JIRA can be found at [1].
>
> - John
>
> [1]: https://issues.apache.org/jira/browse/DELTASPIKE-690
>
>
> On Sun, Aug 17, 2014 at 5:26 PM, John D. Ament <[hidden email]>
> wrote:
>
>> All,
>>
>> Just wondering, can we consider this a binding vote?  Just want to make
>> sure I have the right links in place.
>>
>> John
>>
>>
>> On Mon, Aug 11, 2014 at 12:04 PM, John D. Ament <[hidden email]>
>> wrote:
>>
>>> +1 as well.  I can push this folder in to master after 1.0.2 is release,
>>> so as to not mess up Gerhard.
>>>
>>>
>>> On Mon, Aug 11, 2014 at 11:56 AM, Jason Porter <[hidden email]>
>>> wrote:
>>>
>>>> +1 from me. —
>>>> Sent from Mailbox
>>>>
>>>> On Mon, Aug 11, 2014 at 9:54 AM, Rafael Benevides <[hidden email]>
>>>> wrote:
>>>>
>>>>> I ran the PoC and I do really thing that it works for DeltaSpike
>>>>> (considering that there's no restriction on CMS).
>>>>> Can I give a green sign to Michelle start the docs refactoring (as
>>>>> planned) using Asciidoctor? I think that she and her team can work on
>>>>> its own repository and them move it in one big shot once that we have
>>>>> all requirements setup. Wdyt ?
>>>>> Em 8/11/14, 8:17, John D. Ament escreveu:
>>>>>> @mark
>>>>>>
>>>>>> That's what I based it on actually.
>>>>>>
>>>>>>
>>>>>> On Mon, Aug 11, 2014 at 12:44 AM, Mark Struberg <[hidden email]>
>>>> wrote:
>>>>>>> You can look at batchee.
>>>>>>>
>>>>>>> Romain configured offline doc (with markdown, but could also be
>>>> asciidoc)
>>>>>>> and mvn scm-publish
>>>>>>>
>>>>>>> LieGrue,
>>>>>>> strub
>>>>>>>
>>>>>>>
>>>>>>> --------------------------------------------
>>>>>>> On Sat, 9/8/14, John D. Ament <[hidden email]> wrote:
>>>>>>>
>>>>>>>    Subject: Re: DeltaSpike docs plan
>>>>>>>    To: "deltaspike" <[hidden email]>
>>>>>>>    Date: Saturday, 9 August, 2014, 15:54
>>>>>>>
>>>>>>>    Actually, from digging
>>>>>>>    around their code, might have an easier solution, so
>>>>>>>    long as everyone agrees.
>>>>>>>
>>>>>>>    I have a small POC setup here:
>>>>>>>
>>>>>>>
>>>> https://github.com/johnament/deltaspike/commit/402becc0e450e551570107a1661d39e9eb6a43cb
>>>>>>>    I setup a local VM w/ a SVN
>>>>>>>    repo to test it out.  Basically, we can
>>>>>>>    generate the asciidoc locally using mvn site,
>>>>>>>    then run mvn site-deploy to
>>>>>>>    move the
>>>>>>>    rendered files to staging.  Once done, login to CMS and
>>>>>>>    promote to
>>>>>>>    prod.
>>>>>>>
>>>>>>>    The only change would be to get infra to switch
>>>>>>>    our script to use the shell
>>>>>>>    option.  It
>>>>>>>    does put the rendering process on whoever is writing the
>>>>>>>    docs,
>>>>>>>    but since it's using the java
>>>>>>>    plugin and jruby, nothing should need to be
>>>>>>>    downloaded separately to machines.
>>>>>>>
>>>>>>>
>>>>>>>    On Fri, Aug 8, 2014 at 1:55
>>>>>>>    PM, Rafael Benevides <[hidden email]>
>>>>>>>    wrote:
>>>>>>>
>>>>>>>    > I
>>>>>>>    remember that someone said that CMS already supports
>>>>>>>    remote
>>>>>>>    > repositories. Can't we start
>>>>>>>    by having this documents moved soon while we
>>>>>>>    > discuss about the asciidoc rendering ?
>>>>>>>    >
>>>>>>>    > Em 8/8/14, 10:53,
>>>>>>>    Gerhard Petracek escreveu:
>>>>>>>    >
>>>>>>>    >  @john:
>>>>>>>    >> the
>>>>>>>    infra team is usually not the blocking part (if there is
>>>>>>>    no
>>>>>>>    >> significant
>>>>>>>    >> technical issue and they don't get
>>>>>>>    a new heavy part to maintain).
>>>>>>>    >>
>>>>>>>    >> regards,
>>>>>>>    >>
>>>>>>>    gerhard
>>>>>>>    >>
>>>>>>>    >>
>>>>>>>    >>
>>>>>>>    >> 2014-08-08
>>>>>>>    15:37 GMT+02:00 John D. Ament <[hidden email]>:
>>>>>>>    >>
>>>>>>>    >>  I think we
>>>>>>>    need to convince infra@ that these are all must needed
>>>>>>>    >>> features.
>>>>>>>    >>>   From looking at the
>>>>>>>    code behind CMS, it would appear that it's the one
>>>>>>>    >>> calling markdown based on the
>>>>>>>    imports in our files.  Unless we want to do
>>>>>>>    >>> something crazy like render
>>>>>>>    asciidoc in markdown format, then hand that
>>>>>>>    >>> over for rendering..
>>>>>>>    >>>
>>>>>>>    >>> Still
>>>>>>>    would need to convince that pulling from git over the svn
>>>>>>>    site is
>>>>>>>    >>> ideal as well.
>>>>>>>    >>>
>>>>>>>    >>>
>>>>>>>    John
>>>>>>>    >>>
>>>>>>>    >>>
>>>>>>>    >>> On
>>>>>>>    Fri, Aug 8, 2014 at 9:03 AM, Rafael Benevides <
>>>> [hidden email]>
>>>>>>>    >>> wrote:
>>>>>>>    >>>
>>>>>>>    >>>  Em
>>>>>>>    8/8/14, 6:49, Pete Muir escreveu:
>>>>>>>    >>>>
>>>>>>>    >>>>   On 7 Aug 2014, at
>>>>>>>    18:47, Rafael Benevides <[hidden email]>
>>>>>>>    >>>> wrote:
>>>>>>>    >>>>
>>>>>>>    >>>>>   Before we
>>>>>>>    have a deal with Michelle's team about these content
>>>>>>>    >>>>> changes,
>>>>>>>    >>>>>
>>>>>>>    >>>>>> I think we should
>>>>>>>    close the two other definitions:
>>>>>>>    >>>>>>
>>>>>>>    >>>>>> - docs location: move
>>>>>>>    to deltaspike sources, create a new repository,
>>>>>>>    >>>>>> other?
>>>>>>>    >>>>>>
>>>>>>>    >>>>>>  +1 to move to
>>>>>>>    sources
>>>>>>>    >>>>>
>>>>>>>    >>>>>  +1 to move to sources
>>>>>>>    >>>>
>>>>>>>    >>>>    and
>>>>>>>    >>>>>
>>>>>>>    >>>>>> -docs format: markdown
>>>>>>>    or asciidoc
>>>>>>>    >>>>>>
>>>>>>>    >>>>>>  +1 for asciidoc.
>>>>>>>    >>>>>
>>>>>>>    >>>>>  +1 for asciidoc
>>>>>>>    >>>>
>>>>>>>    >>>>
>>>>>>>    >>>>  However I believe we also
>>>>>>>    need agree on:
>>>>>>>    >>>>>
>>>>>>>    >>>>> * add support for asciidoc
>>>>>>>    to Apache CMS
>>>>>>>    >>>>> * add
>>>>>>>    support for importing external repo to Apache CMS
>>>>>>>    >>>>>
>>>>>>>    >>>>> so that the docs can still
>>>>>>>    be build as part of the website.
>>>>>>>    >>>>>
>>>>>>>    >>>>>   From what
>>>>>>>    people have said in the past, both are possible, if
>>>>>>>    someone
>>>>>>>    >>>>> (e.g. Rafael
>>>>>>>    ;-) can spend a couple of days doing it.
>>>>>>>    >>>>>
>>>>>>>    >>>>>  Definitely I would like
>>>>>>>    to help/handle that. I believe that both
>>>>>>>    >>>>
>>>>>>>    >>>
>>>>>>>    (asciidoc
>>>>>>>    >>>
>>>>>>>    >>>> support + importing external
>>>>>>>    repo) will bring open doors to
>>>>>>>    >>>> documentation
>>>>>>>    >>>> contribution.
>>>>>>>    >>>>
>>>>>>>    >>>>
>>>>>>>    >>>>    I believe that we should
>>>>>>>    propose a vote to decided this, otherwise it
>>>>>>>    >>>>>
>>>>>>>    >>>>>> can become an endless
>>>>>>>    discussion. Wdyt ?
>>>>>>>    >>>>>>
>>>>>>>    >>>>>>
>>>>>>>    >>>>>>
>>>>>>>    >>>>>> Em 8/4/14, 17:28,
>>>>>>>    Gerhard Petracek escreveu:
>>>>>>>    >>>>>>
>>>>>>>    >>>>>>  @suggested content
>>>>>>>    changes:
>>>>>>>    >>>>>>> +1
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>> regards,
>>>>>>>    >>>>>>> gerhard
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>> 2014-08-01 18:46
>>>>>>>    GMT+02:00 Rafael Benevides <[hidden email]
>>>>>>>    >>>>>>> <mailto:[hidden email]>>:
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      Hi all,
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      As you may
>>>>>>>    known, Red Hat docs team was called to help on
>>>>>>>    >>>>>>>      DeltaSpike
>>>>>>>    docs. After a long period, they have analyzed the
>>>>>>>    >>>>>>>
>>>>>>>    documentation and bring us an awesome plan that is
>>>>>>>    available
>>>>>>>    >>>>>>>
>>>>>>>    here:
>>>>>>>    >>>>>>>
>>>>>>>    https://docs.google.com/document/d/186f_
>>>>>>>    >>>>>>>
>>>>>>>    amQ9XuREq8FcO7orxvOjQZtvEEYa7WPj1e8p8bM/edit#heading=h.4sqhyz68wgg2
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      The
>>>>>>>    document is opened for comments.
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      Something
>>>>>>>    that was also discussed not only inside Red Hat but
>>>>>>>    >>>>>>> with
>>>>>>>    >>>>>>>      some
>>>>>>>    community members is about the format and source of the
>>>>>>>    >>>>>>>
>>>>>>>    documentation. I strongly believe that we should have the
>>>>>>>    >>>>>>>
>>>>>>>    documentation somewhere else but the DS site source. It
>>>>>>>    could
>>>>>>>    >>>>>>>
>>>>>>>    improve the ease to the community to contribute with it.
>>>>>>>    Having
>>>>>>>    >>>>>>>
>>>>>>>    said that, it's also suggested that we should use
>>>>>>>    asciidoc as
>>>>>>>    >>>>>>>
>>>>>>>        documentation format.
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      So what we
>>>>>>>    have until now ?
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      - The
>>>>>>>    documentation plan to be reviewed and approved by the DS
>>>>>>>    >>>>>>>      community.
>>>>>>>    Then we can talk about the plans to make it happen.
>>>>>>>    >>>>>>>      - The
>>>>>>>    documentation location: Recommendation to be out of the
>>>>>>>    >>>>>>> site
>>>>>>>    >>>>>>>      source.
>>>>>>>    >>>>>>>      - The
>>>>>>>    documentation format: Suggested to use asciidoc.
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      Please,
>>>>>>>    read the plan and lets discuss about these 3 topics
>>>>>>>    >>>>>>>
>>>>>>>    individually.
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      Michelle
>>>>>>>    Murray (whose team provided the plan and she is copied
>>>>>>>    >>>>>>> on
>>>>>>>    >>>>>>>      this
>>>>>>>    Thread) can follow the feedback.
>>>>>>>    >>>>>>>      --
>>>>>>>    >>>>>>>      *Rafael
>>>>>>>    Benevides | Senior Software Engineer*
>>>>>>>    >>>>>>>      JBoss
>>>>>>>    Developer
>>>>>>>    >>>>>>>
>>>>>>>      M: +55-61-9269-6576 <tel:%2B55-61-9269-6576>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      Red Hat
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      Better
>>>>>>>    technology. Faster innovation. Powered by community
>>>>>>>    >>>>>>>
>>>>>>>    collaboration.
>>>>>>>    >>>>>>>      See how it
>>>>>>>    works at www.redhat.com <http://www.redhat.com/>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>      LinkedIn
>>>>>>>    <http://www.linkedin.com/company/3258288>
>>>>>>>    Youtube
>>>>>>>    >>>>>>>
>>>>>>>    <https://www.youtube.com/redhatlatam>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>
>>>>>>>    >>>>>>>
>>>>>>>    >
>>>>>>>
>>>>>>>
>>>