[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: VOLUNTEER: Port dev docs to a wiki

From: Max Bowsher <maxb_at_ukf.net>
Date: 2005-10-21 02:44:29 CEST

[Note: The message to which I am replying does not seem to have reached the
dev@ list at all. I got it by private copy only, and I can't see it in the
svn.haxx.se archives either]

Jay Levitt wrote:
> Max Bowsher wrote:
>
>> 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.
>
> I'm proposing that by putting it in a wiki, it would in fact get
> updated over time as newbies come on board, read it, spot one or two
> things each that aren't accurate anymore, and fix it. I agree that
> trying to update it as a formal project would be a huge bit of work,
> and probably not an itch that anyone has (like most of the
> documentation). That's what's great about wikis - bite-sized
> refactoring, updating and correcting of documentation, instead of
> only wholesale, highly-motivated rewrites.
>>
>> You mention documents, plural, though - what others were you
>> thinking of?
>
> I was reading the webdav-usage doc to try and understand the protocol
> dumps I'm looking at, but most of the meat is "further info to come".
> I also looked at many of the files in /notes.

I'm sorry, but I personally do not support the idea of putting either
svn-design or webdav-usage in a Wiki. Both are quite technical documents -
assuming that newbies will be able to usefully contribute to them seems
unrealistic to me. The people who can work on these documents are the kind
that have made significant study of the code - this kind of person should
not find sending a patch any sort of barrier. Add to that, that these
documents are ones where peer review of changes is especially valuable, to
ensure that misunderstandings do not propagate into the documentation.
Therefore, I do not think a Wiki is a useful tool in this case.

There is also the point that the target audience of these documents is
people who will write and contribute code - i.e. people who will be sending
patches anyway.

The same arguments apply to notes/.

>> 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.
>
> So how are decisions on policy issues like this made? Rough consensus
> on the list? Should I sum up the revised proposal and ask for approval
> votes? Something else?

Consensus on dev@, voting only if consensus fails to be achieved.

So, we continue this discussion, and see what comes of it.

Max.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Oct 21 02:45:56 2005

This is an archived mail posted to the Subversion Dev mailing list.