DeltaSpike docs plan

classic Classic list List threaded Threaded
12 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 - About documentation format

Rafael Benevides
As talked with Gerhard.

The reasons to use asciidoc are because  it's easily exportable to PDF, HTML, and it's also easy to contribute. It can be used to export also to epub and It can be used to write books...

Em 8/1/14, 13:46, Rafael Benevides escreveu:
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

Jason Porter
In reply to this post by Rafael Benevides
Wow, looks like a lot of work was spent on the analysis of the documentation! Thanks Michelle!

+1 from me for all the suggestions.


On Fri, Aug 1, 2014 at 10:46 AM, Rafael Benevides <[hidden email]> wrote:
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

Antoine Sabot-Durand-2
+1 for me as well. Having the doc source with source code is a must have
IMO.

Antoine Sabot-Durand

Le 4 août 2014 à 17:52, Jason Porter <[hidden email]> a écrit :

Wow, looks like a lot of work was spent on the analysis of the
documentation! Thanks Michelle!

+1 from me for all the suggestions.


On Fri, Aug 1, 2014 at 10:46 AM, Rafael Benevides <[hidden email]>
wrote:

>  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
>
> [image: Red Hat]
>
> Better technology. Faster innovation. Powered by community collaboration.
> See how it works at www.redhat.com
>
> [image: LinkedIn] <http://www.linkedin.com/company/3258288> [image:
> Youtube] <https://www.youtube.com/redhatlatam>
>



--
Jason Porter
http://en.gravatar.com/lightguardjp
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

john.d.ament
In reply to this post by Rafael Benevides
There may be some issues here.  For one, does anyone know if the apache CMS can work in the proposed format?  I believe it's a requirement currently to separate them.


On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides <[hidden email]> wrote:
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

Romain Manni-Bucau
Hi

@John: apache cms is extensible enough to work with what we want (even docx
or xls :p). Just need somebody with 1-2 days to hack the rendering and wire
it in perl in the DS cms integratino.



Romain Manni-Bucau
Twitter: @rmannibucau
Blog: http://rmannibucau.wordpress.com/
LinkedIn: http://fr.linkedin.com/in/rmannibucau
Github: https://github.com/rmannibucau


2014-08-04 18:51 GMT+02:00 John D. Ament <[hidden email]>:

> There may be some issues here.  For one, does anyone know if the apache
> CMS can work in the proposed format?  I believe it's a requirement
> currently to separate them.
>
>
> On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides <[hidden email]>
> wrote:
>
>>  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
>>
>> [image: Red Hat]
>>
>> Better technology. Faster innovation. Powered by community collaboration.
>> See how it works at www.redhat.com
>>
>> [image: LinkedIn] <http://www.linkedin.com/company/3258288> [image:
>> Youtube] <https://www.youtube.com/redhatlatam>
>>
>
>
Reply | Threaded
Open this post in threaded view
|

Re: DeltaSpike docs plan

Rafael Benevides
In reply to this post by john.d.ament
Maybe it's a silly question: Does all Apache project needs to use Apache
CMS ?


Em 8/4/14, 13:51, John D. Ament escreveu:

> There may be some issues here.  For one, does anyone know if the
> apache CMS can work in the proposed format?  I believe it's a
> requirement currently to separate them.
>
>
> On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides
> <[hidden email] <mailto:[hidden email]>> wrote:
>
>     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

Romain Manni-Bucau
Almost: http://www.apache.org/dev/cms.html

What's the issue with CMS?


Romain Manni-Bucau
Twitter: @rmannibucau
Blog: http://rmannibucau.wordpress.com/
LinkedIn: http://fr.linkedin.com/in/rmannibucau
Github: https://github.com/rmannibucau


2014-08-04 20:15 GMT+02:00 Rafael Benevides <[hidden email]>:

> Maybe it's a silly question: Does all Apache project needs to use Apache CMS
> ?
>
>
> Em 8/4/14, 13:51, John D. Ament escreveu:
>>
>> There may be some issues here.  For one, does anyone know if the apache
>> CMS can work in the proposed format?  I believe it's a requirement currently
>> to separate them.
>>
>>
>> On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides <[hidden email]
>> <mailto:[hidden email]>> wrote:
>>
>>     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
It seemed at the first looks that it makes you tight with SVN for repo,
Markdown for format, and doesn't allow you to embed other documents.

Something that came in my mind was to have the documentation as a git
submodule of the DeltaSpike site, that way we can have it linked and
splited at the same time.

Em 8/4/14, 15:17, Romain Manni-Bucau escreveu:

> Almost: http://www.apache.org/dev/cms.html
>
> What's the issue with CMS?
>
>
> Romain Manni-Bucau
> Twitter: @rmannibucau
> Blog: http://rmannibucau.wordpress.com/
> LinkedIn: http://fr.linkedin.com/in/rmannibucau
> Github: https://github.com/rmannibucau
>
>
> 2014-08-04 20:15 GMT+02:00 Rafael Benevides <[hidden email]>:
>> Maybe it's a silly question: Does all Apache project needs to use Apache CMS
>> ?
>>
>>
>> Em 8/4/14, 13:51, John D. Ament escreveu:
>>> There may be some issues here.  For one, does anyone know if the apache
>>> CMS can work in the proposed format?  I believe it's a requirement currently
>>> to separate them.
>>>
>>>
>>> On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides <[hidden email]
>>> <mailto:[hidden email]>> wrote:
>>>
>>>      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

Romain Manni-Bucau
2014-08-04 18:20 GMT+00:00 Rafael Benevides <[hidden email]>:
> It seemed at the first looks that it makes you tight with SVN for repo,

true but you don't have to see it if you don't want

> Markdown for format,

that's the default only

> and doesn't allow you to embed other documents.
>

It does

> Something that came in my mind was to have the documentation as a git
> submodule of the DeltaSpike site, that way we can have it linked and splited
> at the same time.
>

I think we *have* to put the doc in deltaspike (no indirection) to
keep it consistent

> Em 8/4/14, 15:17, Romain Manni-Bucau escreveu:
>
>> Almost: http://www.apache.org/dev/cms.html
>>
>> What's the issue with CMS?
>>
>>
>> Romain Manni-Bucau
>> Twitter: @rmannibucau
>> Blog: http://rmannibucau.wordpress.com/
>> LinkedIn: http://fr.linkedin.com/in/rmannibucau
>> Github: https://github.com/rmannibucau
>>
>>
>> 2014-08-04 20:15 GMT+02:00 Rafael Benevides <[hidden email]>:
>>>
>>> Maybe it's a silly question: Does all Apache project needs to use Apache
>>> CMS
>>> ?
>>>
>>>
>>> Em 8/4/14, 13:51, John D. Ament escreveu:
>>>>
>>>> There may be some issues here.  For one, does anyone know if the apache
>>>> CMS can work in the proposed format?  I believe it's a requirement
>>>> currently
>>>> to separate them.
>>>>
>>>>
>>>> On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides <[hidden email]
>>>> <mailto:[hidden email]>> wrote:
>>>>
>>>>      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
afaik doing the CMS via svnpubsub is only for convenience. We could theoretically also generate the html pages somewhere else. But at the end of the day we need to push it to svn to publish it. This is our way to make sure we have all in a proper historic context. 

LieGrue,
strub


On Monday, 4 August 2014, 20:29, Romain Manni-Bucau <[hidden email]> wrote:
 

>
>
>2014-08-04 18:20 GMT+00:00 Rafael Benevides <[hidden email]>:
>> It seemed at the first looks that it makes you tight with SVN for repo,
>
>true but you don't have to see it if you don't want
>
>> Markdown for format,
>
>that's the default only
>
>> and doesn't allow you to embed other documents.
>>
>
>It does
>
>> Something that came in my mind was to have the documentation as a git
>> submodule of the DeltaSpike site, that way we can have it linked and splited
>> at the same time.
>>
>
>I think we *have* to put the doc in deltaspike (no indirection) to
>keep it consistent
>
>
>> Em 8/4/14, 15:17, Romain Manni-Bucau escreveu:
>>
>>> Almost: http://www.apache.org/dev/cms.html
>>>
>>> What's the issue with CMS?
>>>
>>>
>>> Romain Manni-Bucau
>>> Twitter: @rmannibucau
>>> Blog: http://rmannibucau.wordpress.com/
>>> LinkedIn: http://fr.linkedin.com/in/rmannibucau
>>> Github: https://github.com/rmannibucau
>>>
>>>
>>> 2014-08-04 20:15 GMT+02:00 Rafael Benevides <[hidden email]>:
>>>>
>>>> Maybe it's a silly question: Does all Apache project needs to use Apache
>>>> CMS
>>>> ?
>>>>
>>>>
>>>> Em 8/4/14, 13:51, John D. Ament escreveu:
>>>>>
>>>>> There may be some issues here.  For one, does anyone know if the apache
>>>>> CMS can work in the proposed format?  I believe it's a requirement
>>>>> currently
>>>>> to separate them.
>>>>>
>>>>>
>>>>> On Fri, Aug 1, 2014 at 12:46 PM, Rafael Benevides <[hidden email]
>>>>> <mailto:[hidden email]>> wrote:
>>>>>
>>>>>      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 SHADOW] DeltaSpike docs plan

Pete Muir
In reply to this post by Rafael Benevides

On 1 Aug 2014, at 17:46, Rafael Benevides <[hidden email]> wrote:

> 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.

+1 for the content changes, whatever else. This is the most important thing for the wider community IMO.

> - The documentation location: Recommendation to be out of the site source.

This would be nice. It can then be imported by e.g. an svn submodule or git checkout as part of the site build

> - The documentation format: Suggested to use asciidoc.

+1 asciidoc is really nice, it allows you do a lot of stuff you would like to do in markdown (e.g. tables) but can’t without non-standard extensions.

>
> 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
>
> <{a8aabf3a-4467-4e37-9bc5-48b1d7b494a2}_LATAM_RedHat.jpg>
>
> Better technology. Faster innovation. Powered by community collaboration.
> See how it works at www.redhat.com
>
> <linkedin.png> <youtube.png>