[infinispan-dev] Infinispan documentation

Mon May 16 10:22:04 EDT 2016

On 05/16/2016 03:21 PM, Tristan Tarrant wrote:
> On 16/05/2016 14:31, Sebastian Laskawiec wrote:
>> 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.
> Sure, that is my intention.
>>      - Collapsible Table of Contents
>>
>> +1. But maybe we could rearrange/remove some of them?
> Reorganizing the actual content of the documentation is very much
> needed, but is not part of the scope of this e-mail.
>
>>      - 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.
> It was never my intention to suggest removal of the old docs, just that
> docs/stable and docs/dev would always point to the latest stable and
> unstable docs. Unfortunately, because GitHub pages doesn't support URL
> rewriting, we need to decide whether we want to also have the actual
> "hard version" copies of the docs (i.e. stable AND 8.2.x) at the same time.

What about docs/stable being just

|<html><head><meta http-equiv="refresh" 
content="0;url=http://infinispan.org/docs/8.2"></head><body></body></html>|

(maybe with a link in the body).
I am not sure how well this will work with SEO. Sanne would probably 
know, as Hibernate recently dealed with the same issue.

My 2c

Radim
||
>
>>      - 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).
> Sure.
>>   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
>> <http://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?
> That was just an experiment, I want to keep a look which is as close as
> possible as the current one.
>
> I will probably tackle this in steps, i.e. start with the "stable" +
> "dev" paths, add the collapsible tree, maybe add the js search, and then
> split the docs.
>
> Tristan
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev

-- 
Radim Vansa <rvansa at redhat.com>
JBoss Performance Team