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, 15 Sep 2006 16:03:18 GMT
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


Mime
View raw message