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 <[email protected]> > 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 > >
