camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Willem Jiang <willem.ji...@gmail.com>
Subject Re: [DISCUSS] How to improve the documentation of new functionality (for older releases)
Date Wed, 08 Feb 2012 08:38:27 GMT
If we just apply the bug patch on the branch, it will more easy for us 
to maintain the document.
In this case, we can reuse the Camel 2.8.0 doc for all the other Camel 
2.8.x ...

On Wed Feb  8 15:02:55 2012, 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.mueller@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.
>>
>>
>
>



-- 
Willem
----------------------------------
FuseSource
Web: http://www.fusesource.com
Blog:    http://willemjiang.blogspot.com (English)
         http://jnn.javaeye.com (Chinese)
Twitter: willemjiang 
Weibo: willemjiang 


Mime
View raw message