Max Bowsher wrote:
> [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]
Apologies to all... it seems my rewrite-the-from-line procmail recipe
suddenly stopped liking combined list and non-list recipients, and so
-none- of my posts were reaching the list except through quoted
replies. I think I've worked around that.
>
> Jay Levitt wrote:
>
> 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.
I can see why you would think that, but I must respectfully disagree -
I've seen it work. (http://wiki.rubyonrails.com is a great example.)
No, a brand-new svn developer is not going to be able to rewrite the
whole doc. But they'll be able to point out things that seem unclear,
and make suggested changes, comments, ask inline questions, etc. It's a
much more organic process than the edit-patch-commit process; you
shouldn't try to think of a wiki as just a webby way to edit and commit
doc patches.
Newcomers often make the best reviewers for tech docs, because they'll
ask the basic questions that you realize need to be addressed by the
doc. If I notice something on a wiki that seems wrong or incomplete,
I'll just add a quick note, or a suggested change, or caveats. Other,
more knowledgeable readers will pick up on that, expand and correct my
correction. Eventually someone refactors the section so that the
conversation disappears, and the end result is a corrected section.
It's a living, breathing, collaborative document, with the conversations
and FAQs and reference all integrated.
But with static files, none of that happens. Yes, I could post to the
list to ask if a line in the documentation is still correct, but due to
the high volume here, that's (understandably) discouraged. I'd be
remiss in posting "Hey, I tried the example in the documentation, but
got this error" to the dev list until I did a whole bunch of research
and debugging on my own. By the time I find out the answer ("This
doesn't work when SVNParentPath is used"), I'm ten steps removed from
the docs. I'm not likely to go back and commit a patch to the docs,
especially if the "problem" was my own misunderstanding - yet that's
exactly the type of situation that can help improve documentation.
Yes; occasionally, someone will post something that sounds definitive,
and yet is entirely wrong. But the exact same thing happens in
peer-reviewed, static docs like we have now, because things that were
true when the doc was written are no longer true, or because the writer
(an expert) made certain assumptions that the reader did not. My
contention, and experience, is that the wiki will, on average, be MORE
correct than the static docs.
So wiki changes end up creating a very different model of documentation;
they take advantage of the fact that we can use the same language for
both the document itself and the conversation about the document. I
think a commit e-mail for every wiki commit would create ridiculous
volumes, and be counterproductive. I also think wiki editing should
very explicitly *NOT* be restricted to commiters alone; again, your most
valuable feedback is going to come from someone who's reading this thing
for the first time, and has yet to write a single line of code.
I do think it makes a lot of sense to have the wiki "funnel into" the
static docs, with a proper review process. Perhaps I could integrate
something into a wiki engine that flags any given version of the page as
"reviewed"; if the last editor was not on the commit list, it could say
"This page has not yet been formally reviewed. Click *here* for the
last approved revision.". In fact, that seems like useful wiki
functionality in general. Would that address concerns of documentation
gone wild?
Jay
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Oct 21 04:06:41 2005