cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Little <mark.lit...@jboss.com>
Subject Re: Wiki and Web
Date Mon, 11 Sep 2006 14:31:13 GMT
I think you're right, but the offline aspect is very important. Some  
form of decent and easy-to understand documentation that ships with  
the release is important and won't be replaced by a wiki IMO.

Mark.


On 11 Sep 2006, at 11:56, Oisin Hurley wrote:

> 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


Mime
View raw message