cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dan Diephouse <...@envoisolutions.com>
Subject Re: Wiki and Web
Date Fri, 01 Sep 2006 15:22:09 GMT
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
View raw message