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
