Subject Re: [Firebird-general] Re: Make a wiki and centralize all info about firebird there
Author Paul Vinkenoog
Hi Cosmin,

> > Whether you write directly into a wiki or produce DocBook XML which
> is later rendered to HMTL and PDF doesn't make a hell of a lot of a
> difference.
> Let's see about that (writing your first sentence): read 4 docs, get
> the "sources" via cvs, get the "tools", the "libs", test-run the
> build... I mean are you kidding me??

No, talking from experience. The time I had to invest learning DocBook and setting up the environment was nothing compared to the actual docwriting and maintaining.

Of course, for someone who just makes the odd contribution it's different. That's why people can (and do) contribute in all kinds of formats. Even plaintext is OK. Sooner or later it will get converted by one of the regular writers/translators.

> Now with a wiki, on your bullet-list:
> - the organizing of the material, and structuring the document:
> already there, just make the corresponding topics and sections

Of course it's not already there. You have the *tools* to make topics and sections quickly - just like when writing DocBook in a dedicated editor.

> and copy-paste the content.

Huh? Where does the content come from? It has to be *written* first, doesn't it? Whether it's written by you or by someone else, *someone* has to do (or already have done) the work.

> new pages with a click.

Filled with content, of course ;-)

> conflict resolution with a click (restore older, delete, undelete, etc.)

Not much difference with CVS or SVN here. The tools help, the decisions are human.

> - checking and double-checking facts: forget about it, let whoever
> knows better correct you.

And what if this "whoever" doesn't come around? What if he's too busy coding for Firebird, for example?

But that aside: in order to achieve high reliabity, the checking and double-checking *has* to be done. The point is not whether the author does it himself or if someone else does it; the point is that this too is work, and takes time. And often it's not merely a question of "knowing better" but of investigating, running tests to see what really happens in certain circumstances, etc.

> - formulating the narrative, and trying to explain complex subjects:
> refactoring too easy to care. let whoever's better at words to say it
> better.

Again: it's not about who does it, but that it has to be done. And no matter how good you are at words, technical writing takes time and effort. There's no such thing as a free lunch here - unless of course, you just copy-and-paste other people's work, don't care about whether it's right or wrong, and trust that someone else (or a whole bunch of someone elses) will come along and correct your errors (which in the meantime may have spread to dozens of other sites).

> > Still, I'm glad to see that several people are enthusiastic about
> the wiki concept and I hope that some of them will become active
> contributors. Yes, of course the project could use some fresh blood.
> Lots of it!
> Hear that, "new" faces? Just got the thumbs-up from the big guy of The
> Docs. What more could you want?

A little niceness?

Paul Vinkenoog