Return-Path: Delivered-To: apmail-incubator-cxf-dev-archive@locus.apache.org Received: (qmail 84222 invoked from network); 19 Sep 2006 16:14:08 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 19 Sep 2006 16:14:08 -0000 Received: (qmail 68493 invoked by uid 500); 19 Sep 2006 16:14:08 -0000 Delivered-To: apmail-incubator-cxf-dev-archive@incubator.apache.org Received: (qmail 68456 invoked by uid 500); 19 Sep 2006 16:14:07 -0000 Mailing-List: contact cxf-dev-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: cxf-dev@incubator.apache.org Delivered-To: mailing list cxf-dev@incubator.apache.org Received: (qmail 68447 invoked by uid 99); 19 Sep 2006 16:14:06 -0000 Received: from idunn.apache.osuosl.org (HELO idunn.apache.osuosl.org) (140.211.166.84) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 19 Sep 2006 09:14:06 -0700 X-ASF-Spam-Status: No, hits=0.1 required=5.0 tests=FORGED_RCVD_HELO Received: from ([216.73.126.120:40355] helo=mail.envoisolutions.com) by idunn.apache.osuosl.org (ecelerity 2.1 r(10620)) with ESMTP id 02/F2-28275-94710154 for ; Tue, 19 Sep 2006 09:14:01 -0700 Received: from [10.1.10.180] (c-71-205-132-212.hsd1.mi.comcast.net [71.205.132.212]) by mail.envoisolutions.com (Postfix) with ESMTP id 0213F1009C for ; Tue, 19 Sep 2006 09:06:39 -0700 (PDT) Message-ID: <45101748.2090603@envoisolutions.com> Date: Tue, 19 Sep 2006 12:14:00 -0400 From: Dan Diephouse User-Agent: Mozilla Thunderbird 1.0.2 (Windows/20050317) X-Accept-Language: en-us, en MIME-Version: 1.0 To: cxf-dev@incubator.apache.org Subject: Re: Wiki Spaces (was RE: Wiki and Web) References: <244F5835C09CB641AE1D928BB2B0B9D8025D3E65@amereast-ems2.IONAGLOBAL.COM> In-Reply-To: <244F5835C09CB641AE1D928BB2B0B9D8025D3E65@amereast-ems2.IONAGLOBAL.COM> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N +1 - how about combining #2 & #4 though? - Dan Johnson, Eric wrote: >That sounds like a good idea. Dan K. actually pointed out to me that it >is possible to have multiple spaces and use each one for slightly >different purposes. For example, Geronimo has one for their website, one >for a knowledge base, one for documentation, one for developers, one for >project management, a sandbox, and two others. >I think that may be a bit of overkill, but I do like the idea of having >more than one space for the project. How about we use four spaces: >1. Web site space that we use to create the front page. This space will >only be editable by developers on the commit list. Used for editing the >site and then exported to static HTML. >2. Developer space for putting up development plans, architectural docs, >etc. Also open to the developers on the commit list, plus active >contributors to the code base. >3. Documentation space for user facing docs. Same as above, but also >open to some users. >4. General purpose wiki. Open to the general public and never gets >exported to a static state. >This will give us the benefits you laid out for using confluence and >provide a little bit of control over who can edit what. It will also >mean we can have slightly different presentation templates for different >parts of the site should the need arise. > > > >>-----Original Message----- >>From: Dan Diephouse [mailto:dan@envoisolutions.com] >>Sent: Friday, September 15, 2006 12:03 PM >>To: cxf-dev@incubator.apache.org >>Subject: Re: Wiki and Web >> >>How about we get the wiki structured up a bit and then we can switch >>later if we need to? Maybe try it for M1 and then switch if we need to >>for M2? Or if its clear it isn't working before M1 we can reevaluate >>then too. >> >>- Dan >> >>Johnson, Eric wrote: >> >> >> >>>Debbie, >>>+1 for prettying up the wiki. The addition of a navigation bar would >>>really help make it easier to find content and add a sense of >>> >>> >structure > > >>>to it. If you want to work on this it would be great. >>>As for how to do the documentation, I'm still thinking. Dan D. has >>> >>> >made > > >>>a good case for using the wiki, but I still have concerns. Largely, I >>>think those concerns are more philosophical than practical, but I >>> >>> >need > > >>>to chew on it a bit more. >>>Cheers, >>>Eric >>> >>> >>> >>> >>> >>> >>>>-----Original Message----- >>>>From: Debbie Moynihan [mailto:debbiemoynihan@gmail.com] >>>>Sent: Friday, September 15, 2006 10:31 AM >>>>To: cxf-dev@incubator.apache.org >>>>Subject: Re: Wiki and Web >>>> >>>>I think that both the dynamic wiki based docs and the release level >>>> >>>> >>>> >>>> >>>docs >>> >>> >>> >>> >>>>both have significant value. I do think that the expectation of an >>>> >>>> >>>> >>>> >>>open >>> >>> >>> >>> >>>>source project is not the same as traditional commercial software so >>>> >>>> >>>> >>>> >>>just >>> >>> >>> >>> >>>>wiki based documentation would be acceptable. That said, release >>>> >>>> >>>> >>>> >>>level >>> >>> >>> >>> >>>>documentation would be really beneficial for users and a nice to >>>> >>>> >have. > > >>>> >>>> >>>I >>> >>> >>> >>> >>>>have a lot of experience with customizing templates for communities >>>> >>>> >>>> >>>> >>>and >>> >>> >>> >>> >>>>web-sites and writing copy/documentation (although I am new to >>>> >>>> >>>> >>>> >>>Confluence >>> >>> >>> >>> >>>>but it seems pretty easy). I'd like to volunteer to expand the wiki >>>>format >>>>using Confluence themes (left navigation theme) and best practices >>>> >>>> >>>> >>>> >>>from >>> >>> >>> >>> >>>>apache projects and other confluence based projects listed >>>> >>>> >previously > > >>>> >>>> >>>in >>> >>> >>> >>> >>>>the >>>>thread. Eric would it make sense to hold off and see how the >>>>documentation >>>>progresses for a bit and then determine if we also want to create >>>> >>>> >>>> >>>> >>>separate >>> >>> >>> >>> >>>>formal release level documentation - or if you want to get going on >>>> >>>> >>>> >>>> >>>the >>> >>> >>> >>> >>>>docbook documentation right away you can focus on that and you won't >>>> >>>> >>>> >>>> >>>have >>> >>> >>> >>> >>>>to >>>>learn as much about Confluence. I've done some research on >>>> >>>> >Confluence > > >>>>themes >>>>etc and it seems pretty straightforward, although I will need wiki >>>> >>>> >>>> >>>> >>>admin >>> >>> >>> >>> >>>>privileges (preferred) or I can provide instructions to someone with >>>> >>>> >>>> >>>> >>>admin >>> >>> >>> >>> >>>>privileges. My user name is DebbieMoynihan on Confluence. >>>> >>>>Whatever we decide on the documentation, I think it makes sense to >>>> >>>> >use > > >>>> >>>> >>>the >>> >>> >>> >>> >>>>left nav bar theme so we can see all of the critical links to the >>>> >>>> >left > > >>>>instead of having to scroll to the bottom of the page. >>>> >>>>Debbie >>>> >>>>On 9/12/06, Johnson, Eric wrote: >>>> >>>> >>>> >>>> >>>>>Oisin, >>>>>Your points are well stated as always. I think they hit a lot of >>>>> >>>>> >the > > >>>>>contentions spot on. >>>>>As I writer, I find that wikis are limited for the type of work I >>>>> >>>>> >>>>> >>>>> >>>want >>> >>> >>> >>> >>>>>to do. I want to create formal documentation that supports a stable >>>>>release. This documentation is targeted at users who are developing >>>>>production systems and are not likely to jump to the next hot >>>>> >>>>> >>>>> >>>>> >>>release. >>> >>> >>> >>> >>>>>This type of documentation is not really benefited by agility, is >>>>> >>>>> >>>>> >>>>> >>>highly >>> >>> >>> >>> >>>>>organized, has a consistent level of quality, is thoroughly >>>>> >>>>> >>>>> >>>>> >>>reviewed, >>> >>> >>> >>> >>>>>and follows some pretty tight style guidelines. It has indexes and >>>>> >>>>> >>>>> >>>>> >>>other >>> >>> >>> >>> >>>>>aids to finding information in it. >>>>>However, for developers who want to get documentation about how >>>>> >>>>> >>>>> >>>>> >>>their >>> >>> >>> >>> >>>>>code works or how it is designed a wiki is more than enough. Wikis >>>>>provide a quick and easy way of creating content and keeping it >>>>> >>>>> >>>>> >>>>> >>>updated. >>> >>> >>> >>> >>>>>For cutting edge, fluid material they are great. Experience has >>>>> >>>>> >>>>> >>>>> >>>shown me >>> >>> >>> >>> >>>>>that having a wiki available to the engineers does encourage the >>>>> >>>>> >>>>> >>>>> >>>flow of >>> >>> >>> >>> >>>>>information from the developers to the writers. >>>>>I like your idea of a blended approach where developers create >>>>> >>>>> >>>>> >>>>> >>>content >>> >>> >>> >>> >>>>>about their features, and users can add stuff also, using the wiki. >>>>> >>>>> >>>>> >>>>> >>>This >>> >>> >>> >>> >>>>>stuff can be easily published and made easily accessible. In >>>>> >>>>> >>>>> >>>>> >>>addition, >>> >>> >>> >>> >>>>>we can filter that information into formal documentation that is >>>>> >>>>> >>>>> >>>>> >>>more >>> >>> >>> >>> >>>>>tightly controlled for quality, style, tone, message, etc.. The >>>>> >>>>> >more > > >>>>>formal documentation can also be accessed on through the web site >>>>> >>>>> >>>>> >>>>> >>>and be >>> >>> >>> >>> >>>>>released as a separate package if that makes sense. >>>>>I know this seems like a "corporate" way of thinking, but there >>>>> >>>>> >must > > >>>>> >>>>> >>>be >>> >>> >>> >>> >>>>>a good reason that there is a whole industry out there for creating >>>>>formal documentation for popular open source projects. >>>>>Cheers, >>>>>Eric >>>>> >>>>> >>>>> >>>>> >>>>> >>>>>>-----Original Message----- >>>>>>From: Hurley, Oisin >>>>>>Sent: Monday, September 11, 2006 6:57 AM >>>>>>To: cxf-dev@incubator.apache.org >>>>>>Subject: Re: Wiki and Web >>>>>> >>>>>>Lots of interesting points here on the documentation aspect of the >>>>>>project, and I'm enjoying the thread :) Of course I can't resist >>>>>>adding my 2c, in bullet point form. >>>>>> >>>>>> * having worked as a developer for a number of years, I have >>>>>>regularly seen releases 'released via press release' and then >>>>>>the documentation follow the code within a 30 day ship window >>>>>> >>>>>> * having used OSS for a number of years, I have regularly seen >>>>>>documentation updated at a very fine-grained level and in a >>>>>>timely fashion when bugfixes happen...also I have seen >>>>>> >>>>>> >>>>>> >>>>>> >>>documentation >>> >>> >>> >>> >>>>>>that never actually appears :) >>>>>> >>>>>> * I disagree that wikis are unprofessional, I think that they >>>>>>are very acceptable - if it's good enough for IBM, BEA, Oracle, >>>>>>SAP and co. (http://www.osoa.org/display/Main/Home) then I think >>>>>>is has made it's professional debut. However, some wikis can >>>>>>look awful *cough*moinmoin*cough* :) >>>>>> >>>>>> * I, personally, find it easier to write for wiki than docbook, >>>>>>purely because I level of tooling required for wiki is less than >>>>>>that required for docbook given a set level of productivity. >>>>>>However, if I was writing full-time or mostly full-time, then I >>>>>>wouldn't use the wiki, I would use docbook. >>>>>> >>>>>> * I, personally, find wikis very frustrating because I can't >>>>>>update them offline without copying and pasting. Some day I >>>>>>will need to fix this. >>>>>> >>>>>> * I, personally, think that using a wiki strengthens the >>>>>> >>>>>> >>>>>> >>>>>> >>>developers >>> >>> >>> >>> >>>>>>connection to the document and increases their resolve to actually >>>>>>update the thing in the first place. Remember that one of the >>>>>>big challenges a tech writer has is actually getting information >>>>>>out of the developers - blood/stone and all that (generalization >>>>>>alert :) >>>>>> >>>>>> * I, personally, think that a developer is not anywhere as >>>>>> >>>>>> >>>>>> >>>>>> >>>likely >>> >>> >>> >>> >>>>>>to be able to write as well as a tech writer, so I think >>>>>>that it is a positive thing for those skilled in the exposition of >>>>>>technical to filter/review the documentation. >>>>>> >>>>>>Of course, after making all those points the only conclusion that >>>>>>I can come to is that we might need to end up with a blended >>>>>> >>>>>> >>>>>> >>>>>> >>>approach, >>> >>> >>> >>> >>>>>>so that during the development cycle developers can update a wiki, >>>>>>so that snapshots are up-to-date documented, and then coming up >>>>>>to a release perhaps the documentation developers can engage to >>>>>>move, prune, clean and otherwise sanitize the wiki content and >>>>>>transfer it to a docbook format for a doc release synched with >>>>>>the software release. That way everyone gets to use their own >>>>>>fave tools, the code devs can make fine-grained immediate >>>>>>changes to pieces of wiki and doc devs can have a fairly reliable >>>>>>corpus upon which to base release doc. >>>>>> >>>>>>Thoughts? >>>>>> >>>>>> --oh >>>>>> >>>>>> >>>>>> >>>>>> >>>>> >>>>> >>> >>> >>> >>-- >>Dan Diephouse >>(616) 971-2053 >>Envoi Solutions LLC >>http://netzooid.com >> >> > > > > -- Dan Diephouse (616) 971-2053 Envoi Solutions LLC http://netzooid.com