<html><head><meta http-equiv="Content-Type" content="text/html charset=iso-8859-1"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On 28 Jan 2013, at 11:17, Mircea Markus <<a href="mailto:mmarkus@redhat.com">mmarkus@redhat.com</a>> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On 25 Jan 2013, at 09:15, Galder Zamarreņo wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><br>On Jan 24, 2013, at 2:51 PM, Manik Surtani <<a href="mailto:manik@jboss.org">manik@jboss.org</a>> wrote:<br><br><blockquote type="cite">Guys<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">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.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">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].<br></blockquote><br>Dan did some experiments last year and you can see some results here too:<br><a href="https://plus.google.com/114112334290393746697/posts/CdXJt6hVn5A">https://plus.google.com/114112334290393746697/posts/CdXJt6hVn5A</a><br><br>Source: <a href="http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc">http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc</a><br>Result: <a href="http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html">http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html</a><br><br><blockquote type="cite">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.<br></blockquote><blockquote type="cite"><br></blockquote><blockquote type="cite">Then a root 'docs' folder to contain the table of contents and other organisational attributes, and scripts in 'bin' to generate the documentation.<br></blockquote><br>+1<br><br><blockquote type="cite">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.<br></blockquote><br>^ 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.<br><br><blockquote type="cite">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.</blockquote></blockquote><br></div><div>All sounds good! Not sure how Disqus would be used though - instead of github annotations?</div><div>This is my understanding on how docs will be updated:</div><div>- when a functionality is changed the documentation(<module-name>/src/docs) is updated in the same pul request</div></div></blockquote><blockquote type="cite"><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>- the reviewer, besides the code also checks the documentation and comments on github <-- is this step that you want to be replaced with Dusqus?</div></div></blockquote><div><br></div><div>The process you defined with GitHub pull requests is correct, for cases where the documentation is enhanced to support a new feature in the code. </div><div><br></div><div>I wanted to add Disqus as a mechanism for anyone reading the documentation to ask questions about the documentation, add more information from real-world experiences, or report fixes to the documentation. E.g., suggest that something isn't clear, isn't addressed, is incorrect or to provide additional information.</div><div><br></div><div>Similar, for example, to the "User Contributed Notes" section of the PHP documentation (I've picked some random pages here - scroll towards the bottom to find the User Contributed Notes):</div><div><br></div><div><a href="http://php.net/manual/en/language.operators.string.php">http://php.net/manual/en/language.operators.string.php</a></div><div><a href="http://php.net/manual/en/language.oop5.traits.php">http://php.net/manual/en/language.oop5.traits.php</a></div><div><br></div><div>MySQL has something similar:</div><div><br></div><div><a href="http://dev.mysql.com/doc/refman/5.5/en/create-database.html">http://dev.mysql.com/doc/refman/5.5/en/create-database.html</a></div><div><a href="http://dev.mysql.com/doc/refman/5.5/en/drop-index.html">http://dev.mysql.com/doc/refman/5.5/en/drop-index.html</a></div><div><br></div><div><br></div><div>--</div></div><div><span class="Apple-style-span" style="border-collapse: separate; border-spacing: 0px; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; border-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; border-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>Manik Surtani</div><div><a href="mailto:manik@jboss.org">manik@jboss.org</a></div><div><a href="http://twitter.com/maniksurtani">twitter.com/maniksurtani</a></div><div><br></div><div><div>Platform Architect, JBoss Data Grid</div><div><a href="http://red.ht/data-grid">http://red.ht/data-grid</a></div></div></div></span></div></span></div></span>
</div>
<br></body></html>