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