Jason Dillon wrote:
I think that a documentation system should be a combination of
- reasonably easy to use
- versionable
- able to be used offline
- extractable into an open and transformable format for reuse
Wikis that I've used fail on #2, #3 and #4.
Confluence (as well as other mature wikis) provide #2, and #4 isn't that
really to achieve. Most wikis provide some way to version content.
I mean across pages - like how we do tags and branches, so a doco set
can be associated with a version of G.
It
happens that Confluence uses Hibernate and versioned entities for this
not a SCM like SVN or Perforce. Confluence wiki-markup could itself be
considered that open and transformable format.
So could anything, I suppose :) I was thinking more along the lines of
some XML dialect like DocBook - even if it could export, that would be
cool.
I was thinking about docs the other day - OpenOffice can output DocBook
(which I'm sure everyone on the planet knew except me...), so there now
is an offline, WYSIWYG editor that produces a standard format that
allows transform for various presentation formats.
If you don't like that,
then you could always write a transformer into that language which you
do like.
The question that leaps to mind is what keeps me assured that the
confluence wiki format is stable and not changing?
#3 is the only one that isn't so easy to resolve out of the box. It is
possible however, but is lacking in many ways. For example, you could
setup a Confluence standalone on whatever your mobile workstation was,
then import/export spaces. Its definitely not ideal, but it is possible.
Perhaps someone will write a bidirectional SVN sync, so that you could
update Confluence wiki-markup in SVN, which would then get picked up in
Confluence. While this could be done, there are some issues with
potential merging conflicts, as the definitive copy of the data is in
Confluence (from Confluence's perspective), so if a user offline make
several changes, in addition to online users, there would potentially be
a window of error.
I keep hoping I have some free time to take this on. This is the
canonical detached dataset problem, isn't it? It seems that marging
isn't so hard because it is human-readable textual content, so a merge
process is pretty straightforward in case of collision.
I realize the clear majority is for Confluence, but these factors
should be considered.
There are several... or many (not sure) of us who are aware of these
issues. I've been actively looking at resolving some of them and/or
finding alternatives which will appease most of the interested parties.
For example, I've got a crude Confluence listener which will persist
wiki-markup (w/editor id and comments) to SVN. That gets us closer to a
#2 that more people can agree on. Atlassian are cool/reasonable peeps
so it might be possible to expose the basic versioning/content mechanism
as a plugin to allow us to completly replace that with a SVN impl... but
don't hold your breath.
Using SVN as a backing store would go part of the way, as I can then
setup the Free Local JIRA that those cool peeps at Atlassian would give
away for single-machine personal use, aim it at my data tree, and let me
edit away (or a real local WYSIWYG editor...). Then I can just svn co
and deal the any merge issues...
geir
--jason
- Re: [VOTE] Documentation in Confluence, MoinMoin, or.. Geir Magnusson Jr
-
