<div dir="ltr">Hey Tristan!<div><br></div><div>Comments inlined.</div><div><br></div><div>Thanks</div><div>Sebastian</div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, May 16, 2016 at 1:29 PM, Tristan Tarrant <span dir="ltr"><<a href="mailto:ttarrant@redhat.com" target="_blank">ttarrant@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi all,<br>
<br>
just a heads up on my documentation overhaul plan (incidentally the<br>
WildFly guys are also currently discussing their own documentation<br>
issues too on wildfly-dev).<br>
<br>
First of all, I've issued a PR [1] which performs an initial overhaul of<br>
the documentation source files by removing the meaningless "chapter-xx"<br>
prefix, removing obsolete/duplicated sections, replacing mentions of<br>
JBoss AS 7 with WildFly and rearranging some sections so that the flow<br>
is more accurate (i.e. all cachestores as children of persistence,<br>
simple-cache as a child of local-cache, total-order as a child of<br>
transactions, etc).<br>
<br>
The following are issues / tasks I would like to tackle in the near future:<br>
<br>
- Single page vs multiple pages<br>
<br>
While having a single page might be useful in some situation (offline?)<br>
it is cumbersome to navigate and hurts our SEO. Try searching for<br>
"infinispan transactions" and Google still shows the old wiki page.<br></blockquote><div><br></div><div>Can we have both, just like Weld [3][4][5]? Multiple page guide could be more friendly to Google and singe page could be useful for ctrl+f lovers.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">- Collapsible Table of Contents<br>
<br>
Our current TOC is very large (67 lines) and it is always expanded. This<br>
means that readers need to scroll to find what they are looking for. I<br>
think that providing an expandable/collapsible tree would be ideal.<br></blockquote><div><br></div><div>+1. But maybe we could rearrange/remove some of them?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">- Merging the guides<br>
<br>
By introducing a multi-page approach, the reason to split our different<br>
guides (getting started, user, server, faq) becomes less of a necessity.<br></blockquote><div><br></div><div>+1000</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">- Versioning<br>
<br>
Currently the documentation for each version is available under<br>
docs/major.minor/. I would like to have semantic names for our main docs<br>
instead (i.e. "stable" and "dev"). Unfortunately this means that searching<br></blockquote><div><br></div><div>I agree, but having version is also very useful. </div><div><br></div><div>Just a couple of days ago I was searching through Weld 2.2.SP1 documentation looking for some configuration parameters which were removed in the latest version. I assume many of our users do the same with Infinispan.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">- Alternative formats<br>
<br>
Asciidoc makes it easy to produce alternative formats and I think we<br>
should generate PDF, EPUB and single HTML as well available as separate<br>
downloads.<br></blockquote><div><br></div><div>+1 for PDF and Single page HTML. I'm not sure about EPUB (at least I haven't heard about anyone using this format for reading a manual).</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
I've been playing with the "webhelp" style available in docbook and I<br>
got [2] (be warned, it's a partial upload) which has many of the<br>
advantages I'm looking for (and more, like an integrated search), but<br>
some shortcomings as well. In particular each web page is ~145KB of<br>
which 132KB of the sidebar, which I guess could be extracted into an iframe.<br></blockquote><div><br></div><div>To be honest I'm not a big fan of docbook style but probably that's because the way I work with the documentation. Usually I try to search a manual using ctrl+f or when the it's is more complicated (or split into multiple sections), I often use google with site:<a href="http://infinispan.org">infinispan.org</a> (this is just an example). That's why I always like single page manuals - I can find everything I need pretty quickly. But I assume I'm not in the majority, am I?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
<br>
Comments and suggestions are obviously welcome<br>
<br>
Tristan<br>
<br>
[1] <a href="https://github.com/infinispan/infinispan/pull/4345" rel="noreferrer" target="_blank">https://github.com/infinispan/infinispan/pull/4345</a><br>
[2] <a href="http://www.dataforte.net/infinispan/configuring_cache.html" rel="noreferrer" target="_blank">http://www.dataforte.net/infinispan/configuring_cache.html</a></blockquote><div>[3] <a href="http://weld.cdi-spec.org/documentation/">http://weld.cdi-spec.org/documentation/</a></div><div>[4] <a href="https://docs.jboss.org/weld/reference/latest/en-US/html_single/">https://docs.jboss.org/weld/reference/latest/en-US/html_single/</a></div><div>[5] <a href="https://docs.jboss.org/weld/reference/latest/en-US/html/">https://docs.jboss.org/weld/reference/latest/en-US/html/</a> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><br>
<span class=""><font color="#888888">--<br>
Tristan Tarrant<br>
Infinispan Lead<br>
JBoss, a division of Red Hat<br>
_______________________________________________<br>
infinispan-dev mailing list<br>
<a href="mailto:infinispan-dev@lists.jboss.org">infinispan-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/infinispan-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/infinispan-dev</a><br>
</font></span></blockquote></div><br></div></div>