Hi Achim,
in theory I like creating documentation from the same source as the
code. The ability to version it together sounds appealing.
The problem is that some things are different to code:
People who write documentation are often different from developers. So
they often prefer more accessible tools.
The other thing is that while it may seem the documentation is linked to
a certain version this is not true in practice. For example it is quite
common to
release a functionality and refine the documentation for it later. So
while you do not want the code to change after it is released you often
want the documentation to
change.
The third thing is that the confluence wiki is the only solution I know
that has a decent support for creating grahpics for the documentation
(gliffy http://www.gliffy.com/). Those graphics can really improve
documentation. With text files in subversion I do not know any simple
way to achieve the same.
I am not even too sure about the requirement for sveral outputs. I think
almost all users of camel and cxf use the web instead of the pdf
version. So I am not sure how much value this other format has.
Christian
Am 17.06.2011 10:37, schrieb Achim Nierbeck:
Hi Christian,
nice Try :-)
actually I like the way the page works right now, it's just something
that needs a bit more "tweaking".
I'd rather see the current process enhance a bit. The generation of
HTML and PDF out of the documentation
in code, I rather like. This way the documentation is "closer" to the code.
It's just that certain pages which are more dynamic than the manual
could be written in Confluence and
be "subpaged"
another thing I would like to see is a "trunk based" documentation to
show the current documentation
this way People are closer to the current development.
Regards, Achim
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
