CXF's website is being moved over to a buildbot build with the results being checked in to SVN. When that is complete (filed the initial INFRA request yesterday), we'll at least be able to tag the docs that were "current" for any release. It's a bit early to move the Camel site to the same process, but I expect we'll have to by the end of the year. Content and such remains in confluence, but the output ends up in SVN for publishing.
Dan On Wednesday, February 08, 2012 8:02:55 AM Christian Schneider wrote: > I would also try to keep the documentation as simple as possible. > Documentation is often maintained by different people than the > developers. Currently we have the advantage that people > can help with the documentation without being developers. This is an > easy way to do first steps in camel. Using an scm we would loose this. > > Then having branches for the documentation would mean that people have > to backport everything. Probably this would quite often be forgotten. > > Another very important thing is to keep documentation always at the same > place. In Karaf documentation is managed in scm and then published to > the website. As the path to the documentation > contains the version number it always changes. So peoples links become > stale and google also can not index this very well. So I think this way > of organizing documentation may have a negative impact on > the visibility and so perhaps also popularity of karaf. > > I think the way documentation is organized in Camel is quite good. It is > just important that we delete references to unsupported versions from > time to time to keep the documentation clean. Of course part of the problem > is that we have an increased number of releases since we do bugfix > releases. Perhaps we should simply not backport functionality in > bugfixes. This would also mean that we have less to document. > > Christian > > Am 08.02.2012 04:08, schrieb Glen Mazza: > > I'm not sure that needs to be done -- the documentation should be > > relevant for the latest version of each branch (2nd digit) of Camel. > > > > So in your example below, the documentation should just state what is > > available in the latest versions of each branch--i.e., 2.7.5, 2.8.3, > > 2.9.1, etc.--and not need to cover intermediate versions within the > > branch. A user should be working with the latest version of each > > branch, if there's a new feature available farther down the branch > > that he or she wants then they will need to upgrade to that later > > version. (If the matter is really significant, yes, the docs *could* > > specify that something is available only in 2.7.5 and not earlier.) > > > > As a practical matter, there is very little available in (say) 2.75 > > not available in 2.71-2.74 -- the documentation would be 99.9% the > > same. Any solution that tries to increase that accuracy to 100% by > > exploding the number of versions of documents to be maintained would > > not improve the documentation but actually degrade it. With multiple > > doc versions: 2.7.1, 2.7.2, 2.7.3, etc., people would be less likely > > to want to update (and proofread) the docs given the knowledge that > > they would have to update so many separate versions in the process. > > Reduced updating results in less useful documentation. > > > > That said, there could be a case to move some of the documentation to > > Docbook under SCM--Apache QPid currently uses a dual Docbook / Wiki > > system. > > > > Glen > > > >> On Sun, Jan 15, 2012 at 6:55 AM, Christian Müller< > >> > >> christian.muel...@gmail.com> wrote: > >>> > At present it's really hard to document new features/improvements > >>> > >>> which we > >>> > >>> > back port to older Camel releases. Eg. we have to mention an > >>> > >>> option is > >>> > >>> > available in 2.7.5, 2.8.3, 2.9.1 and 2.10.0+ but not in 2.8.0, > >>> > >>> 2.8.1, 2.8.2 > >>> > >>> > and 2.9.0. This is really puzzling. -- Daniel Kulp dk...@apache.org - http://dankulp.com/blog Talend Community Coder - http://coders.talend.com
