On 17 June 2011 09:58, Christian Schneider <ch...@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: ja...@fusesource.com Web: http://fusesource.com Twitter: jstrachan, fusenews Blog: http://macstrac.blogspot.com/ Open Source Integration and Messaging
