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 Fri, 08 Sep 2006 19:41:51 GMT


> -----Original Message-----
> From: Dan Diephouse [mailto:dan@envoisolutions.com]
> Sent: Friday, September 08, 2006 12:14 PM
> To: cxf-dev@incubator.apache.org
> Subject: Re: Wiki and Web
> 
> 
> 
> Johnson, Eric wrote:
> 
> >Dan,
> >In terms of developing a Web site, and documentation, it appears we
are
> >coming at this from different points of view. From my point of view
as
> >someone whose focus is on documentation, messaging, and Web design
> >taking an hour to polish up a Web page or a piece of documentation is
> >not an egregious burden. I would imagine that you spend as much
effort
> >testing the code base before releasing it. A professional Web site
> >should not need to be updated on a daily basis. It, like the released
> >version of a product, should be well tested and reviewed before being
> >published. This does make it more difficult to make updates to the
site,
> >but it also ensures that updates are well thought out and vetted
before
> >being made.
> >
> >
> I disagree. First, I don't actually believe that this is how
> documentation is created. Often a release is pushed out and then
> documentation is written. Documentation has a life of its own beyond
> just the initial release.

Having worked as a doc writer for a number of years, I have never seen a
release pushed out with out documentation. The documentation often does
get improved after the initial release, but it is solid before hand. My
experience is entirely based on working for a company that wants to sell
software, not an open source project however.

> Second, I am of the philosophy that documentation should be part of
the
> continuous improvement cycle of the project and it is impossible to
> separate out from developing and support of users. For instance, with
I
> read the xfire user's list and a question comes up that isn't
addressed
> in the docs, I go and write something, then point users to it. Or I
> write a response and ask users to add to the docs. (a lot of times
they
> even do a really thorough job).
> 
> I think the wikipedia provides a great example. It goes through
> continuous improvement and people watch it religiously for any
> backtracks. This makes documentation much more agile and makes it much
> more open/approach to others.

I too think that documentation is an ongoing process and as people come
up with new issues, use cases, and other suggestions for improvement the
documentation should be updated. I also like the idea that any user can
add information about the product. However, I also think that you need
to have both a place where user supplied information can live and a
separate place where documentation that has been reviewed, vetted, and
given an official stamp of approval lives. Most teachers I know would
not accept Wikipedia as a valid reference for information simply because
it does not have a strict review process. I'm going to go out on a limb
and guess that most major companies, who we hope are going to use
CeltiXfire, are not going to accept documentation that is on a wiki as
sufficient.

> 
> >The same would go for versioned, official documentation. The source
> >should be stored in the project trunk with the code and built as part
of
> >the project. When a version of the product is released, the vetted
and
> >reviewed documentation can be packaged and delivered as part of the
> >download. It can then also be pushed out to the Web site.
> >
> >
> I disagree that documentation should be so strictly version with the
> project as it often continues to improve outside of the release cycle.
> Docs are never done.
> 
How do you keep the documentation aligned with releases? What if an
outside entity, such as IONA, wants to consume and repackage the
documentation for a particular release?

> >This does not preclude a developer from documenting a new feature, or
> >adding supplemental documentation, through the wiki. In fact, that is
> >probably the best place for it.
> >
> Why is that the best place? It is outside the normal docs and harder
to
> find,
> 
It does not have to be harder to find, but it does mean that it is
clearly placed outside of the official set of documentation.

> >If the community feels that information
> >on the wiki should be moved into the official documentation, then a
task
> >can be submitted and the work can be done to make that happen. If
not,
> >then it can stay on the wiki. Links can be added to the main page to
> >make such forms of documentation easily accessible.
> >
> >Here is what I propose:
> >1. The main Web site for the project is done in HTML. This means
anybody
> >with HTML knowledge can make updates.
> >2. The Web site is only republished when there is a need to update it
> >and the community, or an elected member of the community, has
reviewed
> >the content.
> >3. The main Web site has at least one link to the Wiki where people
are
> >free to add FAQ's, documentation, and other stuff. If something there
> >meets muster, a link to it can be added to the main site or the
content
> >can be ported to the main site.
> >4. If project members have blogs or other links they want published
> >those too can be added to the main site if the community thinks it is
> >appropriate.
> >5. Official, versioned documentation is written using DocBook XML 4.2
> >and the source is stored in the trunk along with the code.
> >6. The official, versioned documentation is built along with the code
> >and is part of the official product release.
> > - There are open-source XSLT stylesheets that can be used to build
nice
> >looking, customizable HTML and PDF output from this source.
> >7. Other documentation can be written on the wiki. If the community
> >thinks it belongs in the official set, it can be ported.
> >
> >
> I've thought long and hard about this, but I'm -1. I think we should
do
> it all in the wiki. Many projects do it (for instance Dojo uses
JotSpot)
> and it works very well. I think doing it all in the wiki is more
> inclusive, agile, and community focused.

All in all I agree that a wiki is a great way to encourage community
contribution and provides a fast way to get content produced. However,
they also present problems such as versioning, image, structure,
indexing, navigability... Once you get beyond a few bits of
documentation, a Wiki can get cumbersome to navigate. They also, in my
opinion, lack a certain amount of credibility and professionalism. The
Apache Web server and Tomcat don't use wikis for their docs and I doubt
their users would be pleased if they decided to switch to a wiki.

> 
> Cheers,
> 
> - Dan
> 
> --
> Dan Diephouse
> (616) 971-2053
> Envoi Solutions LLC
> http://netzooid.com



Mime
View raw message