karaf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Filippo Balicchia <fbalicc...@gmail.com>
Subject Re: Problems with karaf documentation
Date Sun, 03 Mar 2013 13:27:35 GMT
Hi,

I'm fully agree with with the first two points
>- Links should be as stable as possible, so google as well as other
websites can link to us
>- Google should link to a current and useful page when given a search term
related to a karaf feature like "karaf security" or similar


Probably I don't understand well the the third point, but Is there not the
risk to have page not much organic ?
I'm not UX expert but have too much link in home page is not too heavy ?

>- It should be possible to link directly to a certain feature. So the
documentation should be available in separate pages per feature


Regards

--Filippo

2013/3/3 Christian Schneider <chris@die-schneider.net>

> Somehow our documentation seems to be broken. I was looking for some nice
> pointer to the features plugin to reference in a stackoverflow answer.
>
> When I go to http://karaf.apache.org/index/**documentation.html<http://karaf.apache.org/index/documentation.html>none
of the links there work.
> The documentation in http://repo.maven.apache.org/**
> maven2/org/apache/karaf/**manual/2.3.0/manual-2.3.0.html<http://repo.maven.apache.org/maven2/org/apache/karaf/manual/2.3.0/manual-2.3.0.html>is
only for 2.3.0 and is not really useable as it is just one large page.
>
> I also found that basically all google search point to removed pages.
> E.g. the first hit for "karaf kar" points to http://karaf.apache.org/**
> manual/2.2.6/users-guide/kar.**html<http://karaf.apache.org/manual/2.2.6/users-guide/kar.html>which
is already removed.
>
> I think this is due to the way we structure and publish documentation. We
> create a new uri for each karaf bugfix version. This means that google will
> link to some "random" bugfix version for any given search.
> As we do not want to keep these documentations for all time the links will
> sooner or later end in a 404. I think this concept does not make sense.
> Even if we would never remove documentations the problem is that google
> will often point to older versions that would not be very helpfull to our
> users.
>
> I would like to offer the web documentation in a layout with the following
> goals:
> - Links should be as stable as possible, so google as well as other
> websites can link to us
> - Google should link to a current and useful page when given a search term
> related to a karaf feature like "karaf security" or similar
> - It should be possible to link directly to a certain feature. So the
> documentation should be available in separate pages per feature
>
> So I propose to change our approach slightly:
> We should only have documentation for the big branches of karaf. Currently
> I think this would be 2.2.x, 2.3.x and 3.x
> In the future I think it would make sense to only have documentation for
> each major release in the web. So it would be:
> 2.x, 3.x, 4.x
>
> Each documentation would then reflect the newest released version of each
> major version of karaf. This would allow to have very stable links for
> google and we would still be able to reflect the big changes of major
> releases.
> Of course we should still have a fixed documentation for each karaf
> release but I propose to only deliver this inside the karaf distro not on
> the web.
>
> I think the separate pages goal should already work as I am quite sure we
> had this. So I guess the deployment just did not work.
>
> So what do you think?
>
> Christian
>
> --
>  Christian Schneider
> http://www.liquid-reality.de
>
> Open Source Architect
> Talend Application Integration Division http://www.talend.com
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message