cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hani Suleiman <h...@formicary.net>
Subject Re: Wiki and Web
Date Wed, 30 Aug 2006 17:53:05 GMT
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
>
>


Mime
View raw message