[infinispan-dev] Infinispan documentation

Hi all, just a heads up on my documentation overhaul plan (incidentally the WildFly guys are also currently discussing their own documentation issues too on wildfly-dev). First of all, I've issued a PR [1] which performs an initial overhaul of the documentation source files by removing the meaningless "chapter-xx" prefix, removing obsolete/duplicated sections, replacing mentions of JBoss AS 7 with WildFly and rearranging some sections so that the flow is more accurate (i.e. all cachestores as children of persistence, simple-cache as a child of local-cache, total-order as a child of transactions, etc). The following are issues / tasks I would like to tackle in the near future: - Single page vs multiple pages While having a single page might be useful in some situation (offline?) it is cumbersome to navigate and hurts our SEO. Try searching for "infinispan transactions" and Google still shows the old wiki page. - Collapsible Table of Contents Our current TOC is very large (67 lines) and it is always expanded. This means that readers need to scroll to find what they are looking for. I think that providing an expandable/collapsible tree would be ideal. - Merging the guides By introducing a multi-page approach, the reason to split our different guides (getting started, user, server, faq) becomes less of a necessity. - Versioning Currently the documentation for each version is available under docs/major.minor/. I would like to have semantic names for our main docs instead (i.e. "stable" and "dev"). Unfortunately this means that searching - Alternative formats Asciidoc makes it easy to produce alternative formats and I think we should generate PDF, EPUB and single HTML as well available as separate downloads. I've been playing with the "webhelp" style available in docbook and I got [2] (be warned, it's a partial upload) which has many of the advantages I'm looking for (and more, like an integrated search), but some shortcomings as well. In particular each web page is ~145KB of which 132KB of the sidebar, which I guess could be extracted into an iframe. Comments and suggestions are obviously welcome Tristan [1] https://github.com/infinispan/infinispan/pull/4345 [2] http://www.dataforte.net/infinispan/configuring_cache.html -- Tristan Tarrant Infinispan Lead JBoss, a division of Red Hat