karaf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From James Strachan <ja...@fusesource.com>
Subject Re: Karaf first birthday concall minute notes
Date Fri, 17 Jun 2011 09:24:46 GMT
On 17 June 2011 09:58, Christian Schneider <chris@die-schneider.net> wrote:
> 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.

Using a text area in a web browser is more accessible than editing a
file on a file system? Or do you imagine folks are gonna come along
who totally grok complex technology like OSGi containers or ESB stuff;
but who can't grasp source control and editing files?


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

You can do that too; you can have documentation branches and merge
things from code <-> doc branches as and when required. Have a
'current website' branch and choose what gets updated when.


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

Oh please. Seriously? jpg, gif, visio, omnigraffle, graphviz... You
can't think of any way of making some graphics and checking them into
source code?


> Those graphics can really improve documentation.

Sure, graphics rock. Not liking wikis for opens source project
documentation doesn't mean you don't like pictures.


> With text files in subversion I do not know any simple way to achieve the
> same.

I heard they figured out how to store binary files too in source
control. Did you know you can check them in if you want to?

-- 
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/

Open Source Integration and Messaging

Mime
View raw message