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 09:55:45 GMT
Hi James,

Am 17.06.2011 11:24, schrieb James Strachan:
>
> 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 problem is not the text editor. It is the number of steps needed to 
edit the documentation. Especially as a non committer it is quite 
frustrating.
Please seem my answer to guillaumeĀ“s mail. There I described how many 
steps and people you need to do a small change on the documentation.
>> 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.
This sounds nice in theory and I also voted to do documentation this way 
in a project at my former employer. The problem was that the
documentation that flourished nicely in the wiki started to starve when 
we changed to subversion. Only developers were making changes the user 
did not a single change.
While they participated nicely in the wiki.

In the end we found that most people are interested in the most current 
documentation. Sometimes it will not reflect their perhaps old version 
of the software anymore
but at least they know it is the most current one and all the experience 
from for example mailing list discussions went into it.
>> 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?
The problem is not with checking them into the code. The problem is the 
whole workflow. You have to edit the file with your grahpical tool, save 
it, call some conversion
process to make it viewable on the web. Then this conversion process has 
to be created at first. You also have to install the grahpical tool 
first. There is no readily available solution.
In confluence you click on the diagram. Gliffy opens and when you save, 
it is visible to everyone. That is a completely different experience.

Christian


-- 
--
Christian Schneider
http://www.liquid-reality.de

Open Source Architect
Talend Application Integration Division http://www.talend.com


Mime
View raw message