Jay Levitt wrote:
> I'm noticing that most of the major documents are several years old,
> and obviously pre-1.0.
Which docs are you speaking of?
The "svn-design" texinfo document has always been an unchanging snapshot of
the project's early design goals.
If you are proposing to update, that, then that document alone would be a
significant project in it's own right.
You mention documents, plural, though - what others were you thinking of?
> In theory, everyone could contribute today to these docs; they're in
> SVN, and we could submit patches. In reality, the effort of going
> through a patch submission just to clarify some language or add a
> helpful tip is a barrier. (My existence proof is, again, the state of
> the docs.) Meanwhile, there's talk about how to automate processes so
> the project can handle more developers. Well, have -I- got a solution
> for -you-.
>
> From my brief experience with developer wikis in the Rails world,
> wikis are better at staying current. Technically, they're no
> different than checked-in text files as we have today. But you're
> read them online, and if you see something that needs changing, you
> click a button and change it, right then and there. They tend to
> need "gardening" once in a while, to refactor a bunch of comments
> into a more coherent form, but they remain updated due to their more
> interactive nature; every reader's an editor. And, of course, they're
> revision-controlled. There have been problems with wiki spam, but
> that's easily solvable with minimal access controls/registration.
The one point on which I hesitate is the lack of review of changes implied
by the wiki method.
If a wiki was to be used, I think it would need to support the review of
changes by a group of appropriately authorized users. To not stray to far
away from the wiki concept, I'd OK with unreviewed changes still being
displayed, just so long as, long-term, there is a way to ensure at least one
committer has confirmed the correctness of changes.
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Oct 20 17:53:12 2005