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. > > Thoughts, comments? +1 to Disquss too. > > Cheers > Manik > > [1] http://www.methods.co.nz/asciidoc/ > [2] https://docs.jboss.org/author/display/ISPN/Home > [3] > https://raw.github.com/jboss-jdf/jdf-collateral/master/scripts/ticket-monster.asciidoc > [4] > https://github.com/jboss-jdf/jdf-collateral/blob/master/scripts/ticket-monster.asciidoc > [5] http://disqus.com/ > > -- > Manik Surtani > [email protected] > twitter.com/maniksurtani > > Platform Architect, JBoss Data Grid > http://red.ht/data-grid > > > _______________________________________________ > infinispan-dev mailing list > [email protected] > https://lists.jboss.org/mailman/listinfo/infinispan-dev -- Galder Zamarreño [email protected] twitter.com/galderz Project Lead, Escalante http://escalante.io Engineer, Infinispan http://infinispan.org _______________________________________________ infinispan-dev mailing list [email protected] https://lists.jboss.org/mailman/listinfo/infinispan-dev
