cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dan Diephouse <...@envoisolutions.com>
Subject Re: Wiki and Web
Date Mon, 11 Sep 2006 14:32:33 GMT
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. (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
>


-- 
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog


Mime
View raw message