Mailing-List: contact cxf-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cxf-dev@incubator.apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Message-ID: <44F84F20.3040601@envoisolutions.com>
Date: Fri, 01 Sep 2006 11:17:52 -0400
From: Dan Diephouse <dan@envoisolutions.com>
User-Agent: Mozilla Thunderbird 1.0.2 (Windows/20050317)
MIME-Version: 1.0
To: cxf-dev@incubator.apache.org
Subject: Re: Wiki and Web
References: 
 <244F5835C09CB641AE1D928BB2B0B9D8025D35B6@amereast-ems2.IONAGLOBAL.COM>
In-Reply-To: 
 <244F5835C09CB641AE1D928BB2B0B9D8025D35B6@amereast-ems2.IONAGLOBAL.COM>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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
(616) 971-2053
Envoi Solutions LLC
http://netzooid.com