Hey Tristan!

Comments inlined.

Thanks

Sebastian

On Mon, May 16, 2016 at 1:29 PM, Tristan Tarrant <ttarrant@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