Hey Tristan! Comments inlined.
Thanks Sebastian On Mon, May 16, 2016 at 1:29 PM, Tristan Tarrant <ttarr...@redhat.com> wrote: > 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. > 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. > - 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. > +1. But maybe we could rearrange/remove some of them? > - 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. > +1000 > - 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 > I agree, but having version is also very useful. 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. > - 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. > +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). > > 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. > 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:infinispan.org (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? > > > Comments and suggestions are obviously welcome > > Tristan > > [1] https://github.com/infinispan/infinispan/pull/4345 > [2] http://www.dataforte.net/infinispan/configuring_cache.html [3] http://weld.cdi-spec.org/documentation/ [4] https://docs.jboss.org/weld/reference/latest/en-US/html_single/ [5] https://docs.jboss.org/weld/reference/latest/en-US/html/ > > -- > Tristan Tarrant > Infinispan Lead > JBoss, a division of Red Hat > _______________________________________________ > infinispan-dev mailing list > infinispan-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev >
_______________________________________________ infinispan-dev mailing list infinispan-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev