On 25 Jan 2013, at 09:15, Galder Zamarreño wrote: > > On Jan 24, 2013, at 2:51 PM, Manik Surtani <[email protected]> wrote: > >> Guys >> >> So one of the things coming soon is a revamped documentation site for >> Infinispan. I am thinking of moving to AsciiDoc [1] in place of our current >> Confluence [2] setup, so that documentation can be authored offline, page >> loads will be much faster, etc. >> >> To see what the source files may look like, have a look at the source for >> this guide to TicketMonster [3] and the corresponding rendered output [4]. > > Dan did some experiments last year and you can see some results here too: > https://plus.google.com/114112334290393746697/posts/CdXJt6hVn5A > > Source: > http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc > Result: http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html > >> Now what I propose is a separate section in each maven module for >> documentation (e.g., core/src/docs and cachestores/cloud/src/docs, etc) >> which would contain an AsciiDoc page for each section. >> >> Then a root 'docs' folder to contain the table of contents and other >> organisational attributes, and scripts in 'bin' to generate the >> documentation. > > +1 > >> Further, I propose a separate git repository for the Infinispan website >> (which will be modernised and moved to Awestruct), which in turn will have >> build scripts to clone the infinispan repository, generate documentation, >> and publish documentation alongside the website. > > ^ You probably want this to happen not only at publish time, but also when in > developer mode? i.e. when you're in `awestruct -d` mode. Could be scripted of > course. > >> Now this means the docs will not be editable online. So I propose again >> using Disqus [5] to allow people to comment on each page of documentation, >> which can then be updated as a pull request.
All sounds good! Not sure how Disqus would be used though - instead of github annotations? This is my understanding on how docs will be updated: - when a functionality is changed the documentation(<module-name>/src/docs) is updated in the same pul request - the reviewer, besides the code also checks the documentation and comments on github <-- is this step that you want to be replaced with Dusqus? Cheers, -- Mircea Markus Infinispan lead (www.infinispan.org)
_______________________________________________ infinispan-dev mailing list [email protected] https://lists.jboss.org/mailman/listinfo/infinispan-dev
