cxf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dan Diephouse <...@envoisolutions.com>
Subject Re: Wiki Spaces (was RE: Wiki and Web)
Date Tue, 19 Sep 2006 16:14:00 GMT
+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 <Eric.Johnson@iona.com> 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 <language-of-choice> 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


Mime
View raw message