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: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. (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
>>
>


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


Mime
View raw message