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.
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
