The short answer:
Subversion has no wiki, whether someone likes it or not. Subversion is an
excellent project with excellent document in the docbook-based format. In
fact, Subversion if one of the few projects I've seen to use this xml-based
content stuff well for good, useful application, in a tremendously-helpful
user manual.
Further background:
Patrick, it was not my attention to present a condescending tone; I
apologize if you or anyone else was offended by my text. Further, I did
not want to start a long email thread, but now that we have, I suppose it's
worth finishing it off.
For what it's worth, my project (which will be open-sourced soon) has a
significant amount of docs for Subversion usage in wiki; I really can't
train svn users without it. The svn docbook docs are great, but they are
simply not concise enough for some procedures, etc, even thought my
internal wiki docs DO NOT replace the svn docbook content. One has to
remember: there are tremendous number of users out there which are not
going to understand the depths of subversion; ie, there a lot of
non-programmers using subversion for project/corporate content control.
We are debating whether or not to "internalize" our svn wiki docs when our
project goes public, because some of our users will be asking similar
questions. I'd MUCH RATHER go edit a common Subversion wiki and
collaboratively work with the Subversion community on this structured
content without having to go edit docbook stuff...for I doubt that most of
this content is docbook-manual-oriented applicable. Further, I think this
structured "middleground" content could be like a stagring-read/farm-system
for the Docbook-based manual, as need be (although I don't see much overlap).
Also for what it's worth, projects I've managed and used *have* found
wiki's to be a "golden hammer" of doc stuff; managers and non-technical
people that were previously nowhere to be found in the stream of a
project's content reading and real-time creation are now "part of the
game." Executive managers rave about the wiki; I now have a synergy in a
project like I've never seen before. Further, I've used other project
wikis (RT, MediaWiki, mail2forum.com, Boost, many others) that were, imho,
indispensable. Forums/lists constantly point to ever-evolving wiki pages
to answer continual questions (and the answerees often have additional
perspective on how to adjust the docs), store procedures that are not
pertinent for a "classic" book, etc. Wikis are also so useful and popular,
imho, in large part because they present a "middle ground" of structured
content management between discussions (email lists, newsgroups, and web
forums) and proper content management (like XML-based content
"databases"/formats like Subversion-controlled Docbook files).
One could argue: why not use a Docbook-xml-svn engine instead of a wiki
engine? The primary answer, imo: it's too hard and too formal. The wiki
paradigm is particularly powerful for its ease of use for many powerful
features (that docbook-svn may not offer) and it's instant re-publishing,
integration with web stuff, etc.
An aside: I find that a project tends to gravitate to using what it makes
(beyond an email list). Bugzilla tracks most everything through bug
database. Mailman uses almost exclusively email and a automated-faq
system. MediaWiki uses almost exclusively a wiki--and has a lot of
discussions in the wiki, too. phpBB has many mods to make a web forum do
more then a web forum...and of course all the content references are
threaded web-forum link. And Subversion uses a subversion-controlled
content control. Alas, there's a lot of "it's not build here" stuff going
on in at least some of these projects, and imho, it's unfortunate, for if
this projects could be leverage more of these tools, I think the projects
would be more effective.
In the end, I would prefer all structured project content (for Subversion
or any of ther project) to have a common XML "database" for which wiki or
docbook/html/whatever output is simple an input/output filter, compound
documents can be "programmed" (and therefore content modules can be reused
just like code modules), and there is theoretically no more debate becasue
the wiki andthe docbook content are almost the same thing, just with
different faces.
Alas, this sort of integration is not prevalent yet, although Boost seems
to be trying it out
(<http://www.boost.org/doc/html/boostbook.html>). Maybe there's others.
Bottom line: Subversion doesn't have a wiki, for better or
worse. Interjecting a wiki in the Subversion culture may not be good
thing, in the sense that the current culture seems to be working, and
introducing change to that culture may be risky, and it could confuse
stakeholders.
If my soon-to-be-public project starts to be a reference for Subversion
usage, please don't kill the messenger. :)
-Matt
At 4/7/2006 10:59 AM, Patrick Burleson wrote:
>On 4/7/06, Matt England <mengland@mengland.net> wrote:
> > At 4/7/2006 10:19 AM, Marc Haisenko wrote:
> > >On Friday 07 April 2006 16:59, Matt England wrote:
> > > > Hello,
> > > >
> > > > Does the Subversion project have a wiki? If not, I propose that
> it's worth
> > > > making one.
> > >
> > >Why ?
> >
> > If the answer is not obvious, I'm not sure I wish to pursue the resulting
> > discussion. You're welcome to continue with the status quo, and docbook
> > editing will probably suffice for the formal stuff and may be a better way
> > to coalesce the proper info.
> >
> > Best regards,
> > -Matt
> >
>
><rant>
>I don't appreciate the condescending tone of wiki users when others
>don't want (or "see" ) the use of a wiki. They are not some "golden
>hammer" of project documentation. Personally, I've never, ever, been
>on a project that used a wiki successfully. Not to mention the myriad
>of project wikis I've been to that are woefully out of date because
>it's just not worth it to document things in 2 places (the Wiki, and
>the official docs that get distributed, if there are docs at all), or
>people add pages and no one maintains them (because it doesn't
>interest them and the original person has moved on).
>
>If they work for you, great. But they don't work for everybody, much
>like most tools.
></rant>
>
>I think for Subversion, having members of the core team writing a free
>book, always updating it with the latest feature information, is a way
>to go. It seems to have worked well for this project.
>
>If you do feel passionately enough about it, you could start up a SVN
>wiki and get things going. And if it gets popular, I'm betting you
>could convince the SVN devs to link to it.
>
>Patrick
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Fri Apr 7 20:03:06 2006