cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Matt Raible" <mrai...@gmail.com>
Subject Re: Wiki and Web
Date Mon, 11 Sep 2006 02:53:00 GMT
On 9/10/06, Dan Diephouse <dan@envoisolutions.com> wrote:
> Johnson, Eric wrote:
> >> 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.
> >
> >
> My experience is that in OSS, while some areas may be solid, a lot of it
> will probably suck due to the rapid nature of change. Most docs will
> continue to be improved past the initial release.
> >> 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.
> >
> >
> I think you're throwing a lot FUD at wikis here that is undeserved. We
> aren't trying to convince a teacher here, we're trying to to create the
> best overall documentation for the projects user. While there may not be
> quite the delay before publishing, I think the wikipedia makes up for
> that in its agility and extensiveness. I don't think that you can say
> that the documentation won't be reviewed either. People will be watching
> the documentation.  There are many projects out there that use wikis and
> they can work very well. I don't think anyone is going to object simply
> because its a wiki. Do people not use OpenSymphony projects
> (http://www.opensymphony.com/) because they are backed by a wiki? Or
> ActiveMQ (http://activemq.org/site/home.html)? Or dozens of others?
>
> >>> 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?
> >
> Documentation can be aligned by creating a new wiki space with each
> major version and copying the old docs over. For consumers - you could
> export the docs as XML/HTML/etc. You could even write an xslt
> transformation to turn the confluence xml export into docbook. If IONA
> feels that people want a cleaned up/docbook'd version of the wiki they
> could always provide that as a value add.
>
> > 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.
> >
> >
> Let me address your concerns:
> Image: Create a good template for confluence. OpenSymphony has a decent one.
> Structure: Confluence is a hierarchical wiki, allowing you to create
> structure.
> Indexing: Just create a Navigation page for the lefthand navigation and
> an index page for the user's guide.
> Navigability: See above.
> Professionalism: I disagree that a wiki is unprofessional. If you have a
> good template, it doesn't need to look like a wiki. The OpenSymphony
> site looks better than a lot of apache sites to me. Take Tomcat for
> example: Tomcat has the most horribly ugly documentation.

I think Stripes is one of the best examples of good documentation via
Confluence:

http://stripes.mc4j.org

Then again, Spring's documentation looks excellent using DocBook:

http://static.springframework.org/spring/docs/2.0.x/reference/index.html

I'll be interested to see which route you go.  It's an interesting
idea to author in Confluence and export to DocBook.

Matt

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

Mime
View raw message