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, 05 Sep 2006 15:32:58 GMT
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.
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.
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. 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.

This makes it easy for developers to create content, and it provides a
needed review layer before content is made public.

Cheers,
Eric

> -----Original Message-----
> From: Dan Diephouse [mailto:dan@envoisolutions.com]
> Sent: Friday, September 01, 2006 3:42 PM
> To: cxf-dev@incubator.apache.org
> Subject: Re: Wiki and Web
> 
> Johnson, Eric wrote:
> > Dan,
> > That is close to what I was originally proposing to do.
> > While I don't understand why writing a long piece of documentation
on a
> > wiki is any easier than writing it using a WSYWIG editor that
supports
> > HTML or DocBook
> 1. Often you need to work at the source level of HTML/DocBook
> 2. There is an additional generate, commit & publish cycle when docs
go
> live.
> 3. There is no snippet macro, which means no unit testing of examples
> 
> 
> To expand on #2: I've done static sites at Apache and they're a pain.
A
> typical cycle:
> 1. Write docs.
> 2. Generate on your local machine/
> 3. Check that things are formatted correctly.
> 4. Commit to SVN.
> 5. Log on to Minotaur and issue an SVN update
> 6. Check that everything deployed correctly.
> 
> Go back and repeat. You can see how fixing a link becomes a 10 minute
> process.  This is a deterrent to improving docs. I improve the XFire
> docs probably once a day. Can you imagine how much time this would
take
> out of life if I did that?
> > I accept that asking developers who are busy writing
> > code to learn a new tool is a hassle.
> Its not about learning a tool, I'm happy to learn a DocBook or
whatever,
> I just want to find the best tool for the job.
> > It is possible to allow user
> > facing docs to go up on the wiki as drafts and then, once they have
been
> > reviewed and polished up, be moved into a static area and a format
that
> > is consumable by outside projects - such as IONA.
> >
> That might be an option.
> > I am more than happy to do the grunt work of keeping a non-wiki home
> > page and static user docs up to date. That is what I do for a living
and
> > since my Java skills are less than enterprise grade, I cannot really
> > help out with submitting code...
> >
> I appreciate you volunteering, but I don't think you're going to be
> doing all the doc writing. While IONA is a large part of the project
> others will be writing about features which they themselves
implemented,
> that IONA probably won't have any interest in. So I think we need to
> pick our documentation tools with the realization that we're trying to
> get many people involved.  A good example of this is an XFire
migration
> guide? XFire developers will probably need to write that as we're the
> only people qualified people.
> 
> I'm not trying to rag on any of your suggestions here or say we can't
go
> down the static route, I just want to evaluate what the best option
is.
> 
> So I guess I'd like to know: what tools are you thinking about using
and
> for what type of content?
> 
> - Dan
> 
> --
> Dan Diephouse
> Envoi Solutions
> http://envoisolutions.com
> http://netzooid.com/blog



Mime
View raw message