6:29 a.m.
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.
- 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.
- 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.
- 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
- 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.
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.
Comments and suggestions are obviously welcome
Tristan
[1] https://github.com/infinispan/infinispan/pull/4345
[2] http://www.dataforte.net/infinispan/configuring_cache.html
--
Tristan Tarrant
Infinispan Lead
JBoss, a division of Red Hat
7:31 a.m.
Hey Tristan!
Comments inlined.
Thanks
Sebastian
On Mon, May 16, 2016 at 1:29 PM, Tristan Tarrant <ttarrant(a)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(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev
8:21 a.m.
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
9:22 a.m.
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>...
(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(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev
--
Radim Vansa <rvansa(a)redhat.com>
JBoss Performance Team
9:57 a.m.
On 16/05/2016 16:22, Radim Vansa wrote:
What about docs/stable being just |<html><head><meta
http-equiv="refresh"
content="0;url=http://infinispan.org/docs/8.2"></head>...
(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.
No, redirect wouldn't help. I've also asked a friend who
told me that
the "primary" docs should have a rel="canonical" meta tag
Tristan
9:59 a.m.
On 16 May 2016 at 15:22, Radim Vansa <rvansa(a)redhat.com> wrote:
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>...
(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.
We're aware of having such SEO issues but didn't solve them yet :-/
You don't want to redirect though. You also don't want to have copies
of the documentation in multiple places, at least not without clearly
marking which one is the canonical (the only authoritative) source.
This can be done either by adding more meta fields in the HTML header,
or by inserting them in the HTTP headers.
The HTTP headers approach seems to score best, but Hibernate can't use
that as documentation is hosted on a server out of our control - so is
Github pages for Infinispan.
I'd recommend to host your own httpd server, or deploy on cloudfront:
this would also give you better performance (especially by having more
control on caching options and proxy pragma settings), and better
performance makes both users and SEO happy.
Sanne
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(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev
--
Radim Vansa <rvansa(a)redhat.com>
JBoss Performance Team
_______________________________________________
infinispan-dev mailing list
infinispan-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev
2916
days inactive
2916
days old
infinispan-dev@lists.jboss.org
5 comments
4 participants
participants (4)
-
Radim Vansa -
Sanne Grinovero -
Sebastian Laskawiec -
Tristan Tarrant