cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dan Diephouse <>
Subject Re: Wiki and Web
Date Mon, 11 Sep 2006 14:40:18 GMT
Yes, that is what I was thinking.
- Dan

Mark Little wrote:
> I suppose if the wiki is meant as the main place for documentation 
> then we could always take a snapshot of it prior to release and bundle 
> that as HTML/PDF. Is that what you were thinking too?
> Mark.
> On 11 Sep 2006, at 15:32, Dan Diephouse wrote:
>> Just an FYI - confluence has nice HTML/PDF export functions that can 
>> be used for bundling in distributions.
>> - Dan
>> Mark Little wrote:
>>> 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. ( 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
>> --Dan Diephouse
>> Envoi Solutions

Dan Diephouse
Envoi Solutions

View raw message