cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Debbie Moynihan" <debbiemoyni...@gmail.com>
Subject Re: Wiki and Web
Date Fri, 01 Sep 2006 16:25:15 GMT
Hi,
I created a new project description and capabilities list for CeltiXfire as
a first pass so that we can get some content up onto the web-site that Eric
has volunteered to get going.  I'm attaching as an rtf file for everyone to
take a look.  If it would be better to post it somewhere let me know.  I was
going to take a look at creating some FAQs next.

Deb


On 9/1/06, Dan Diephouse <dan@envoisolutions.com> wrote:
>
> One other approach that geronimo has taken is to have their main site
> done by forest or the like, and have a space for their user's guide. See:
>
> http://geronimo.apache.org/documentation.html
> 1.1 docs:
> http://cwiki.apache.org/GMOxDOC11/apache-geronimo-v11-users-guide.html
> 1.0 docs:
> http://cwiki.apache.org/GMOxDOC10/apache-geronimo-v10-users-guide.html
>
> Not saying that they're a model citizen of how to document a project,
> but something to consider.
>
> - Dan
>
> Dan Diephouse wrote:
> > I think you can expand the definition of HTML in Hani's message to
> > include things like DocBook and the like. I agree with the concerns
> > about the wiki, but I also share the concerns about making it hard to
> > write documentation. As a developer, I often write user facing docs,
> > not just developer facing docs, so I feel this directly affects me.
> >
> > I guess at this point I don't really like any of the options. What
> > would be perfect is if Confluence was SVN based and allowed you to
> > lock down the active version of the page.
> >
> > What are people proposing we use for our basic website? And for the
> > user's guide?
> >
> > - Dan
> >
> > Johnson, Eric wrote:
> >
> >> Hani,
> >> The developers wouldn't necessarily have to write HTML documentation.
> >> They could still use the Wiki to write developer facing docs and the
> >> like. We could just link to these from a central web site or use the
> >> export function out of Confluence for this purpose.
> >> My hope is that there will be a separate set of user facing docs that
> >> will be more tightly reviewed for both technical accuracy and
> >> consistency before being published.
> >> Cheers,
> >> Eric
> >>
> >>
> >>
> >>
> >>> -----Original Message-----
> >>> From: Hani Suleiman [mailto:hani@formicary.net]
> >>> Sent: Wednesday, August 30, 2006 1:53 PM
> >>> To: cxf-dev@incubator.apache.org
> >>> Subject: Re: Wiki and Web
> >>>
> >>> I'm torn, I agree that:
> >>>
> >>> 1) Confluence looks like crap
> >>> 2) A wiki is a horrible way of ensuring a consistent and coherent set
> >>> of documentation (case in point, xfire docs)
> >>>
> >>> However:
> >>>
> >>> 1) It is possible to customise the export templates to look less
> >>> retarded and more professional
> >>> 2) Convincing developers to write html documentation is tricky, if
> >>> not impossible, unless you throw money at them.
> >>>
> >>> On Aug 30, 2006, at 1:49 PM, Johnson, Eric wrote:
> >>>
> >>>
> >>>> Dan,
> >>>> I've been thinking about the web site thing a bit more and still
> >>>>
> >> don't
> >>
> >>
> >>>> think Confluence is the way to go for the front page. Here are a
> >>>> few of
> >>>> my concerns:
> >>>> * While Confluence does make editing the content easy it is also
> >>>> pretty
> >>>> limited in its layout capabilities.
> >>>> * If our Wiki and our web site look the same, what is the point of
> >>>> having both?
> >>>> * Since the Confluence instance we are using is not specific to our
> >>>> project, how much control over look and feel do we have over the
> >>>> resulting output?
> >>>> * Can Confluence make use of CSS and Javascript?
> >>>> Mostly, I'm concerned that using Confluence does not provide a good
> >>>> base
> >>>> for creating a really professional looking web presence.
> >>>> The approach I'd prefer is to use straight HTML to build the main
> >>>>
> >> page
> >>
> >>
> >>>> and perhaps some of the other pages. From that base we can add
> >>>> links to
> >>>> the Confluence instance and other content.
> >>>> I understand that this means checking the HTML back into SVN, but
> >>>>
> >> that
> >>
> >>
> >>>> really is not that big an issue in my opinion. It provides a good
> >>>>
> >> way
> >>
> >>
> >>>> for the whole community an opportunity to see what is being added
> >>>> to the
> >>>> page before it gets pushed out to the Apache web server.
> >>>> Cheers,
> >>>> Eric
> >>>>
> >>>>
> >>>>> -----Original Message-----
> >>>>> From: Dan Diephouse [mailto:dan@envoisolutions.com]
> >>>>> Sent: Thursday, August 24, 2006 4:40 PM
> >>>>> To: cxf-dev@incubator.apache.org
> >>>>> Subject: Re: Wiki and Web
> >>>>>
> >>>>> Johnson, Eric wrote:
> >>>>>
> >>>>>> Dan,
> >>>>>> I agree that most of the Celtix stuff is probably irrelevant
to
> >>>>>> CeltiXfire, but figured we needed to start somewhere...
> >>>>>> I can certainly put something simple together that has a project
> >>>>>> description and associated information. It will probably be
easier
> >>>>>>
> >>>> for
> >>>>
> >>>>>> me, initially at least, to put this together using straight
HTML.
> >>>>>>
> >>>> I'm
> >>>>
> >>>>>> sure confluence is easy to use, but I've never actually done
it.
> >>>>>>
> >>>>>>
> >>>>> Its very simple, just go to a page and click Edit :-)
> >>>>>
> >>>>>> For site generation I'm not sure Forrest is actually the best
way
> >>>>>>
> >> to
> >>
> >>
> >>>> go
> >>>>
> >>>>>> either. I just put the Celtix info together as an experiment.
I'm
> >>>>>>
> >>>> not
> >>>>
> >>>>>> sure I like using the Confluence to build the main site either
> >>>>>>
> >>>> though.
> >>>>
> >>>>>> Is there a way to lock down who can edit the content?
> >>>>>>
> >>>>> Yes, only people who we give permission to can edit it.
> >>>>>
> >>>>>> Does this mean that the wiki and the Web site are the same?
> >>>>>>
> >>>>>>
> >>>>> In essence yes. But the wiki gets exported to SVN. Here is an
> >>>>> example:
> >>>>>
> >>>>> The published site: http://incubator.apache.org/activemq/
> >>>>> Confluence: http://goopen.org/confluence/display/ACTIVEMQ/Home
> >>>>>
> >>>>>> I suppose what I'm getting at is that I like the idea of having
a
> >>>>>>
> >>>> wiki
> >>>>
> >>>>>> that people can edit as a tech/dev zone sort of thing, but not
as
> >>>>>>
> >>>> the
> >>>>
> >>>>>> entry to the project. I like the idea of a static site that
is
> >>>>>>
> >>>> reviewed
> >>>>
> >>>>>> before being published as the front of the Web site. I think
the
> >>>>>>
> >>>> front
> >>>>
> >>>>>> page of the Web site should be a static HTML page that is stored
> >>>>>> separately from the wiki. From that page we can link into
> >>>>>>
> >>>> Confluence,
> >>>>
> >>>>>> Maven derived stuff, or Docbook derived stuff. That way the
front
> >>>>>>
> >>>> page
> >>>>
> >>>>>> is more tightly locked down and can present the best face for
the
> >>>>>> project.
> >>>>>>
> >>>>>>
> >>>>> We have a lot of control over who we allow to do edit things, so
I
> >>>>>
> >>>> guess
> >>>>
> >>>>> I don't think it will be that big of an issue. I think the
> >>>>> benefits of
> >>>>> not having the edit/generate/publish cycle outweigh the reviewing.
> >>>>>
> >>>>> Are people going to go defacing the front page? I don't really
> >>>>>
> >> think
> >>
> >>
> >>>> so.
> >>>>
> >>>>> Its the same principle as the wikipedia. The ease of edit outweighs
> >>>>>
> >>>> the
> >>>>
> >>>>> dangers of someone doing something on a page.  All of us have SVN
> >>>>> logs/RSS feeds for the wiki. I watch the changes to the XFire wiki
> >>>>>
> >>>> quite
> >>>>
> >>>>> religously, and will continue to do so for CXF.
> >>>>>
> >>>>>> It can be just straight HTML and thus avoid the generate->publish
> >>>>>>
> >>>> step.
> >>>>
> >>>>> You still need to commit them to svn. With Confluence we can hook
> >>>>>
> >> it
> >>
> >>
> >>>> up
> >>>>
> >>>>> so its just an Edit -> Save.
> >>>>>
> >>>>>> As for the docs, I think we need to have them in a format that
> >>>>>>
> >>>> allows
> >>>>
> >>>>>> other projects to easily consume them and work with them as
they
> >>>>>>
> >>>> want.
> >>>>
> >>>>>> Keeping them in Docbook allows others to take the docs and build
> >>>>>>
> >>>> them
> >>>>
> >>>>>> into their own doc set if they like.
> >>>>>>
> >>>>>>
> >>>>> Yes and no. I assume you're talking about how IONA may want to
> >>>>>
> >> embed
> >>
> >>
> >>>> the
> >>>>
> >>>>> documentation in its products? Wouldn't this only really be a major
> >>>>> issue on things like the users manual? This was why I was
> >>>>>
> >> mentioning
> >>
> >>
> >>>>> that we might want to have a hybrid approach.
> >>>>>
> >>>>>> Cheers,
> >>>>>> Eric
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>>> -----Original Message-----
> >>>>>>> From: Dan Diephouse [mailto:dan@envoisolutions.com]
> >>>>>>> Sent: Thursday, August 24, 2006 2:58 PM
> >>>>>>> To: cxf-dev@incubator.apache.org
> >>>>>>> Subject: Re: Wiki and Web
> >>>>>>>
> >>>>>>> Hi Eric,
> >>>>>>> I'm not sure that all the old Celtix content will be all
that
> >>>>>>>
> >>>>>>>
> >>>>>> relevant.
> >>>>>>
> >>>>>>
> >>>>>>> Probably the tooling stuff will, but I'm looking through
the rest
> >>>>>>>
> >>>> of
> >>>>
> >>>>>> the
> >>>>>>
> >>>>>>
> >>>>>>> celtix website and it doesn't seem like much of it should
come
> >>>>>>>
> >>>>>>>
> >>>>>> wholesale
> >>>>>>
> >>>>>>
> >>>>>>> to Apache.
> >>>>>>>
> >>>>>>> How about we get a simple website with the mailing list,
source
> >>>>>>> repository, and project description up. I think it would
be
> >>>>>>>
> >> easiest
> >>
> >>
> >>>> to
> >>>>
> >>>>>>> just use confluence for this stage and have the html sync/export
> >>>>>>>
> >>>>>>>
> >>>>>> dumped
> >>>>>>
> >>>>>>
> >>>>>>> to the svn repository for our website. If people are really
keen
> >>>>>>>
> >> on
> >>
> >>
> >>>>>>> using forest, thats fine, but I find Confluence+Export removes
> >>>>>>>
> >> the
> >>
> >>
> >>>>>> extra
> >>>>>>
> >>>>>>
> >>>>>>> generation + publish steps.
> >>>>>>>
> >>>>>>> Concurrently, lets figure out what our requirements are
for
> >>>>>>> documentation. I'm not a huge fan of the write, generate,
publish
> >>>>>>> approach. I find the the wiki approach much faster as you
get an
> >>>>>>>
> >>>>>>>
> >>>>>> instant
> >>>>>>
> >>>>>>
> >>>>>>> look at what your docs look like and there is no delay in
> >>>>>>>
> >>>> publishing.
> >>>>
> >>>>>> I
> >>>>>>
> >>>>>>
> >>>>>>> understand we may want to have stuff checked over before
being
> >>>>>>>
> >>>>>>>
> >>>>>> instantly
> >>>>>>
> >>>>>>
> >>>>>>> published though, so maybe we can do a hybrid approach with
the
> >>>>>>>
> >>>> manual
> >>>>
> >>>>>>> as a forest/xdoc/docbook type of thing and the rest of the
site
> >>>>>>>
> >>>> backed
> >>>>
> >>>>>>> by a wiki.
> >>>>>>>
> >>>>>>> Regards,
> >>>>>>>
> >>>>>>> - Dan
> >>>>>>>
> >>>>>>>
> >>>>>>> Johnson, Eric wrote:
> >>>>>>>
> >>>>>>>
> >>>>>>>> I have a Forrest based site ready that contains most
of the
> >>>>>>>>
> >>>> content
> >>>>
> >>>>>>>> ported from the old Celtix site. It could easily be
deployed and
> >>>>>>>>
> >>>>>>>>
> >>>>>> updated
> >>>>>>
> >>>>>>
> >>>>>>>> to include any Xfire content.
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>> -----Original Message-----
> >>>>>>>>> From: Dan Diephouse [mailto:dan@envoisolutions.com]
> >>>>>>>>> Sent: Friday, August 18, 2006 3:24 PM
> >>>>>>>>> To: cxf-dev@incubator.apache.org
> >>>>>>>>> Subject: Re: Wiki and Web
> >>>>>>>>>
> >>>>>>>>> Jason van Zyl wrote:
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>> On 18 Aug 06, at 1:11 PM 18 Aug 06, Johnson,
Eric wrote:
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>> Have we decided on a Wiki to use?
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>> I setup Confluence:
> >>>>>>>>>>
> >>>>>>>>>> http://cwiki.apache.org/confluence/display/CXF
> >>>>>>>>>>
> >>>>>>>>>> We can use it or something else but that's there
for perusal.
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>> I'm deifnitely for using Confluence. It kicks the
pants off
> >>>>>>>>>
> >> Moin
> >>
> >>
> >>>>>> Moin.
> >>>>>>
> >>>>>>
> >>>>>>>>>>> What are we going to do about getting a
web presence for
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>> the project?
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>> We can either create a Maven site, use the autoexport
plugin
> >>>>>>>>>>
> >> for
> >>
> >>
> >>>>>>>>>> Confluence to turn wiki pages into a static
site, or use
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>> something else.
> >>>>>>>>>
> >>>>>>>>> Maybe a good first step would be to hook in the
autoexport
> >>>>>>>>> plugin for Confluence while we investigate our needs
for
> >>>>>>>>> documentation? This would allow us to get a site
up quickly.
> >>>>>>>>>
> >>>>>>>>> - Dan
> >>>>>>>>>
> >>>>>>>>> --
> >>>>>>>>> Dan Diephouse
> >>>>>>>>> Envoi Solutions
> >>>>>>>>> http://envoisolutions.com
> >>>>>>>>> http://netzooid.com/blog
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>> --
> >>>>>>> Dan Diephouse
> >>>>>>> Envoi Solutions
> >>>>>>> http://envoisolutions.com
> >>>>>>> http://netzooid.com/blog
> >>>>>>>
> >>>>>>>
> >>>>>>
> >>>>>>
> >>>>> --
> >>>>> Dan Diephouse
> >>>>> Envoi Solutions
> >>>>> http://envoisolutions.com
> >>>>> http://netzooid.com/blog
> >>>>>
> >>>>
> >>
> >>
> >>
> >>
> >
> >
>
>
> --
> Dan Diephouse
> Envoi Solutions
> http://envoisolutions.com
> http://netzooid.com/blog
>
>

Mime
  • Unnamed multipart/mixed (inline, None, 0 bytes)
View raw message