camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <>
Subject Re: [DISCUSS] How to improve the documentation of new functionality (for older releases)
Date Wed, 08 Feb 2012 07:02:55 GMT
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.


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


Christian Schneider

Open Source Architect
Talend Application Integration Division

View raw message