karaf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <ch...@die-schneider.net>
Subject Re: Karaf first birthday concall minute notes
Date Fri, 17 Jun 2011 08:58:52 GMT
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


Mime
View raw message