On Jan 24, 2013, at 2:51 PM, Manik Surtani <manik(a)jboss.org> 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.
--
Galder Zamarreño
galder(a)redhat.com
twitter.com/galderz
Project Lead, Escalante
http://escalante.io
Engineer, Infinispan
http://infinispan.org