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].
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.
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.
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?
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-mon...
[4]
https://github.com/jboss-jdf/jdf-collateral/blob/master/scripts/ticket-mo...
[5]
http://disqus.com/
--
Manik Surtani
manik(a)jboss.org
twitter.com/maniksurtani
Platform Architect, JBoss Data Grid
http://red.ht/data-grid