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, I accept that asking developers who are busy writing code to learn a new tool is a hassle. 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. 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... Cheers, Eric
> -----Original Message----- > From: Dan Diephouse [mailto:[EMAIL PROTECTED] > Sent: Friday, September 01, 2006 11:22 AM > To: [email protected] > Subject: Re: Wiki and Web > > 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:[EMAIL PROTECTED] > >>> Sent: Wednesday, August 30, 2006 1:53 PM > >>> To: [email protected] > >>> 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:[EMAIL PROTECTED] > >>>>> Sent: Thursday, August 24, 2006 4:40 PM > >>>>> To: [email protected] > >>>>> 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:[EMAIL PROTECTED] > >>>>>>> Sent: Thursday, August 24, 2006 2:58 PM > >>>>>>> To: [email protected] > >>>>>>> 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:[EMAIL PROTECTED] > >>>>>>>>> Sent: Friday, August 18, 2006 3:24 PM > >>>>>>>>> To: [email protected] > >>>>>>>>> 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
