From: Paul Vinkenoog <paul@vi...> - 2007-02-03 00:51:13
My reply to Rodney about the Docu Wiki:
---------- Forwarded message ----------
Date: Thu, 25 Jan 2007 15:27:59 +0100 (MET)
From: Paul Vinkenoog <paul@...>
To: Rodney Gedda <rodney@...>
Subject: Re: Docu Wiki
> Have a look at their reasoning for using a Wiki as the "beta"
> form of their documentation - the most compelling being all
> project members can log in and make small changes as required.
> That means the people who are most knowledgable about a certain
> topic can add the most recent updates and features. Sound good?
> I'm not suggesting a replacement to the existing documentation
> system, but what do you think of setting up a "beta"
> documentation system driven by DokuWiki and inviting all Firebird
> contributors to add the most recent updates to the software as
> they are committed?
I think it could be great, not for our current job but for any new
updates to the software. Of course it will only work if all developers
The current situation is that, when a release is pending (or earlier),
contributors document their updates in "Whatsnew" documents all over
the source tree. Helen Borrie visits those files, tries to make sense
of them, prods developers who are behind schedule on their
documentation tasks, etc. etc., and finally all this information winds
up in the Release Notes.
If nothing else, this type of wiki could be a great alternative to the
Whatsnew stuff. But that's mainly something between Helen and the
For the user manuals we have to base ourselves on what has changed in
*released* versions. That information is already in the Release Notes.
> The final manual would then still look more like a "book" than a
> wiki, but everyone interested in Firebird can still access 99.99% of
> what there is to know instantly over the Web (there will obviously
> be a few errors in the "beta").
I don't think that we should open such a wiki to the public. Many of
our developers are not exactly fluent in English and their
"documentation" is sometimes utterly confusing. Also, during
alpha/beta/rc stages stuff is added that is later changed or removed
again. If you advertise all this in a public, easily accessible place,
people spread the word, copy volatile docs to other sites, and all
these bits of information start leading a life of their own and come
back later to haunt you.
> I suggest this only because we have so much catching up to do
> comapred with other open source databases regarding documentation.
> Anything that will rectify this situation quickly has to be a good
Yes, but I'm afraid it won't help us now in getting the documentation
up to date. It may help a lot in compiling future Release Notes *and*
user docs, though.
Would you mind posting about this in firebird-docs? I think Helen
might be very interested.
By the way, we should keep the doc-related talk in firebird-docs as
much as possible, so others know what we are up to, and can join in.
It also helps keeping the group alive :-)
From: Helen Borrie <helebor@ii...> - 2007-02-03 02:38:06
At 11:51 AM 3/02/2007, you wrote:
>Would you mind posting about this in firebird-docs? I think Helen
>might be very interested.
I like the wiki idea, especially when all that's needed is to fix
grammar and spelling. But you might like to look at the content in
WhatsNew and compare it with the release notes and (in the CVS doc
directory and subdirectories) the readmes. Everything else in the
notes is plucked from the sky on a clear day, i.e. tracking back
through list archives and blogs, sessions in ICQ, private emails and
notes and, failing all else, the Tales of the Brothers Grimm.
Would it work for a wiki? Can't see it.
Apart from the consistency/accuracy risks cited by Paul (and
addressed often before) Wiki isn't a portable format as far as I can
tell. You can view page source and copy/paste some pretty horrendous
HTML. Writing into a wiki is no less trouble than writing into an
XML editor, anyway. So - primary resource stuff in plain text beats
anything other than ready-to-go docbook xml. Not forgetting the
overriding importance of version control...