You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltaspike.apache.org by Antoine Sabot-Durand <an...@sabot-durand.net> on 2014/06/23 20:52:58 UTC
Documentation proposal
Hi all,
This week-end I wanted to check out documentation source to see how to contribute to it.
I took me a lot of time to find where the doc source are. I finally found it in the mailing list thanks to Rafael ;).
That brought me to a more general reflexion around Deltaspike documentation. Here are my 2 cents :
1) Shouldn’t we at least put a link to the site svn to give opportunity to more people to contribute to the doc ?
2) Shouldn’t we move the doc to the project to have it at he same place than the code ?
3) Shouldn’t we use a doc generator that could also produce PDF to have an offline manual (a lot of my former coworkers use to read documentation while commuting). Asciidoctor is my better known tool (I’m using it to manage and generate CDI specification doc) and markdown can be easily translate to asciidoc, but it can be something else.
As a first significant contribution to the project I propose doing 2 and 3.
WDYT?
Antoine Sabot-Durand
———————————————
Twitter : @antoine_sd
CDI co-spec lead & eco-system development
Agorava tech lead
Re: Documentation proposal
Posted by Romain Manni-Bucau <rm...@gmail.com>.
You are right but pretty sure that's not what we want. What we want to do
is to adjust CMS to match our need. I mean CMS was created to get a
consistent doc solution. If some features are missing then we need to add
them. We can first add them to DS only then see if we can generalize them
(we can add a jar in site libs and call it from perl so we can still rely
on java if needed ;)).
Romain Manni-Bucau
Twitter: @rmannibucau
Blog: http://rmannibucau.wordpress.com/
LinkedIn: http://fr.linkedin.com/in/rmannibucau
Github: https://github.com/rmannibucau
2014-06-23 22:07 GMT+02:00 Antoine Sabot-Durand <an...@sabot-durand.net>:
> Thanks Romain for your answer
> Le 23 juin 2014 à 15:41, Romain Manni-Bucau <rm...@gmail.com> a
> écrit :
>
> > Hi Antoine
> >
> > 2014-06-23 20:52 GMT+02:00 Antoine Sabot-Durand <
> antoine@sabot-durand.net>:
> >
> >> Hi all,
> >>
> >>
> >> This week-end I wanted to check out documentation source to see how to
> >> contribute to it.
> >> I took me a lot of time to find where the doc source are. I finally
> found
> >> it in the mailing list thanks to Rafael ;).
> >>
> >> That brought me to a more general reflexion around Deltaspike
> >> documentation. Here are my 2 cents :
> >>
> >> 1) Shouldn’t we at least put a link to the site svn to give opportunity
> to
> >> more people to contribute to the doc ?
> >>
> >
> > +1, on tomee site we added a little button to edit the page (for instance
> > http://tomee.apache.org/examples/ right of the twitter button)
> >
> >
> >> 2) Shouldn’t we move the doc to the project to have it at he same place
> >> than the code ?
> >>
> >
> > +1000 even if almost no apache project does it, personally I almost only
> > update docs if in the same project
> >
> >
> >> 3) Shouldn’t we use a doc generator that could also produce PDF to have
> an
> >> offline manual (a lot of my former coworkers use to read documentation
> >> while commuting). Asciidoctor is my better known tool (I’m using it to
> >> manage and generate CDI specification doc) and markdown can be easily
> >> translate to asciidoc, but it can be something else.
> >>
> >>
> > +1 but needs time since it will need to be integrated with apache cms
> IMHO
> > (ie a generic solution all apache projects will reuse). adoc is nice and
> > usable but maybe we should ping infra to officially support it otherwise
> I
> > think markdown is a better choice (maybe using pandoc to go to pdf)
> >
>
> True except if we consider the doc as a deliverable like binaries. If it’s
> part of the project we could imagine delivery an HTML page and a PDF file
> and put a link in the site. The idea would be to remove the doc from the
> CMS and have the CMS points to it. I don’t know if it fits with Apache
> policy but considering the documentation problem we have, we really should
> do something to encourage contribution.
>
>
> >
> >> As a first significant contribution to the project I propose doing 2
> and 3.
> >>
> >> WDYT?
> >>
> >>
> >> Antoine Sabot-Durand
> >> ———————————————
> >> Twitter : @antoine_sd
> >> CDI co-spec lead & eco-system development
> >> Agorava tech lead
> >>
> >>
>
>
Re: Documentation proposal
Posted by Antoine Sabot-Durand <an...@sabot-durand.net>.
Thanks Romain for your answer
Le 23 juin 2014 à 15:41, Romain Manni-Bucau <rm...@gmail.com> a écrit :
> Hi Antoine
>
> 2014-06-23 20:52 GMT+02:00 Antoine Sabot-Durand <an...@sabot-durand.net>:
>
>> Hi all,
>>
>>
>> This week-end I wanted to check out documentation source to see how to
>> contribute to it.
>> I took me a lot of time to find where the doc source are. I finally found
>> it in the mailing list thanks to Rafael ;).
>>
>> That brought me to a more general reflexion around Deltaspike
>> documentation. Here are my 2 cents :
>>
>> 1) Shouldn’t we at least put a link to the site svn to give opportunity to
>> more people to contribute to the doc ?
>>
>
> +1, on tomee site we added a little button to edit the page (for instance
> http://tomee.apache.org/examples/ right of the twitter button)
>
>
>> 2) Shouldn’t we move the doc to the project to have it at he same place
>> than the code ?
>>
>
> +1000 even if almost no apache project does it, personally I almost only
> update docs if in the same project
>
>
>> 3) Shouldn’t we use a doc generator that could also produce PDF to have an
>> offline manual (a lot of my former coworkers use to read documentation
>> while commuting). Asciidoctor is my better known tool (I’m using it to
>> manage and generate CDI specification doc) and markdown can be easily
>> translate to asciidoc, but it can be something else.
>>
>>
> +1 but needs time since it will need to be integrated with apache cms IMHO
> (ie a generic solution all apache projects will reuse). adoc is nice and
> usable but maybe we should ping infra to officially support it otherwise I
> think markdown is a better choice (maybe using pandoc to go to pdf)
>
True except if we consider the doc as a deliverable like binaries. If it’s part of the project we could imagine delivery an HTML page and a PDF file and put a link in the site. The idea would be to remove the doc from the CMS and have the CMS points to it. I don’t know if it fits with Apache policy but considering the documentation problem we have, we really should do something to encourage contribution.
>
>> As a first significant contribution to the project I propose doing 2 and 3.
>>
>> WDYT?
>>
>>
>> Antoine Sabot-Durand
>> ———————————————
>> Twitter : @antoine_sd
>> CDI co-spec lead & eco-system development
>> Agorava tech lead
>>
>>
Re: Documentation proposal
Posted by Romain Manni-Bucau <rm...@gmail.com>.
Hi Antoine
2014-06-23 20:52 GMT+02:00 Antoine Sabot-Durand <an...@sabot-durand.net>:
> Hi all,
>
>
> This week-end I wanted to check out documentation source to see how to
> contribute to it.
> I took me a lot of time to find where the doc source are. I finally found
> it in the mailing list thanks to Rafael ;).
>
> That brought me to a more general reflexion around Deltaspike
> documentation. Here are my 2 cents :
>
> 1) Shouldn’t we at least put a link to the site svn to give opportunity to
> more people to contribute to the doc ?
>
+1, on tomee site we added a little button to edit the page (for instance
http://tomee.apache.org/examples/ right of the twitter button)
> 2) Shouldn’t we move the doc to the project to have it at he same place
> than the code ?
>
+1000 even if almost no apache project does it, personally I almost only
update docs if in the same project
> 3) Shouldn’t we use a doc generator that could also produce PDF to have an
> offline manual (a lot of my former coworkers use to read documentation
> while commuting). Asciidoctor is my better known tool (I’m using it to
> manage and generate CDI specification doc) and markdown can be easily
> translate to asciidoc, but it can be something else.
>
>
+1 but needs time since it will need to be integrated with apache cms IMHO
(ie a generic solution all apache projects will reuse). adoc is nice and
usable but maybe we should ping infra to officially support it otherwise I
think markdown is a better choice (maybe using pandoc to go to pdf)
> As a first significant contribution to the project I propose doing 2 and 3.
>
> WDYT?
>
>
> Antoine Sabot-Durand
> ———————————————
> Twitter : @antoine_sd
> CDI co-spec lead & eco-system development
> Agorava tech lead
>
>