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.
- 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