Thanks Romain for your answer Le 23 juin 2014 à 15:41, Romain Manni-Bucau <rmannibu...@gmail.com> a écrit :
> Hi Antoine > > 2014-06-23 20:52 GMT+02:00 Antoine Sabot-Durand <anto...@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 >> >>
signature.asc
Description: Message signed with OpenPGP using GPGMail
