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