Lots of interesting points here on the documentation aspect of the
project, and I'm enjoying the thread :) Of course I can't resist
adding my 2c, in bullet point form.
* having worked as a developer for a number of years, I have
regularly seen releases 'released via press release' and then
the documentation follow the code within a 30 day ship window
* having used OSS for a number of years, I have regularly seen
documentation updated at a very fine-grained level and in a
timely fashion when bugfixes happen...also I have seen documentation
that never actually appears :)
* I disagree that wikis are unprofessional, I think that they
are very acceptable - if it's good enough for IBM, BEA, Oracle,
SAP and co. (http://www.osoa.org/display/Main/Home) then I think
is has made it's professional debut. However, some wikis can
look awful *cough*moinmoin*cough* :)
* I, personally, find it easier to write for wiki than docbook,
purely because I level of tooling required for wiki is less than
that required for docbook given a set level of productivity.
However, if I was writing full-time or mostly full-time, then I
wouldn't use the wiki, I would use docbook.
* I, personally, find wikis very frustrating because I can't
update them offline without copying and pasting. Some day I
will need to fix this.
* I, personally, think that using a wiki strengthens the developers
connection to the document and increases their resolve to actually
update the thing in the first place. Remember that one of the
big challenges a tech writer has is actually getting information
out of the developers - blood/stone and all that (generalization
alert :)
* I, personally, think that a developer is not anywhere as likely
to be able to write as well as a tech writer, so I think
that it is a positive thing for those skilled in the exposition of
technical <language-of-choice> to filter/review the documentation.
Of course, after making all those points the only conclusion that
I can come to is that we might need to end up with a blended approach,
so that during the development cycle developers can update a wiki,
so that snapshots are up-to-date documented, and then coming up
to a release perhaps the documentation developers can engage to
move, prune, clean and otherwise sanitize the wiki content and
transfer it to a docbook format for a doc release synched with
the software release. That way everyone gets to use their own
fave tools, the code devs can make fine-grained immediate
changes to pieces of wiki and doc devs can have a fairly reliable
corpus upon which to base release doc.
Thoughts?
--oh
