cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Johnson, Eric" <Eric.John...@iona.com>
Subject RE: Wiki and Web
Date Tue, 12 Sep 2006 13:54:40 GMT
Oisin,
Your points are well stated as always. I think they hit a lot of the
contentions spot on.
As I writer, I find that wikis are limited for the type of work I want
to do. I want to create formal documentation that supports a stable
release. This documentation is targeted at users who are developing
production systems and are not likely to jump to the next hot release.
This type of documentation is not really benefited by agility, is highly
organized, has a consistent level of quality, is thoroughly reviewed,
and follows some pretty tight style guidelines. It has indexes and other
aids to finding information in it.
However, for developers who want to get documentation about how their
code works or how it is designed a wiki is more than enough. Wikis
provide a quick and easy way of creating content and keeping it updated.
For cutting edge, fluid material they are great. Experience has shown me
that having a wiki available to the engineers does encourage the flow of
information from the developers to the writers.
I like your idea of a blended approach where developers create content
about their features, and users can add stuff also, using the wiki. This
stuff can be easily published and made easily accessible. In addition,
we can filter that information into formal documentation that is more
tightly controlled for quality, style, tone, message, etc.. The more
formal documentation can also be accessed on through the web site and be
released as a separate package if that makes sense.
I know this seems like a "corporate" way of thinking, but there must be
a good reason that there is a whole industry out there for creating
formal documentation for popular open source projects.
Cheers,
Eric

> -----Original Message-----
> From: Hurley, Oisin
> Sent: Monday, September 11, 2006 6:57 AM
> To: cxf-dev@incubator.apache.org
> Subject: Re: Wiki and Web
> 
> 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