[infinispan-dev] Infinispan documentation

[Sebastian Laskawiec]

Hey Tristan!

Comments inlined.

Thanks
Sebastian

On Mon, May 16, 2016 at 1:29 PM, Tristan Tarrant <ttarrant at 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/infinispan-dev/attachments/20160516/b062a549/attachment-0001.html