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 <anto...@sabot-durand.net>: > 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 > >> > >> > >
