Mailing-List: contact cxf-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cxf-dev@incubator.apache.org
Received-SPF: pass (idunn.apache.osuosl.org: domain iona.com designates
 62.221.12.33 as permitted sender)
Mime-Version: 1.0 (Apple Message framework v752.2)
In-Reply-To: 
 <244F5835C09CB641AE1D928BB2B0B9D8025D3A25@amereast-ems2.IONAGLOBAL.COM>
References: 
 <244F5835C09CB641AE1D928BB2B0B9D8025D3A25@amereast-ems2.IONAGLOBAL.COM>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-Id: <7AFA8D6B-DC17-43D1-ABDD-444DEFA2E925@iona.com>
Content-Transfer-Encoding: 7bit
From: Steve Vinoski <vinoski@iona.com>
Subject: Re: Wiki and Web
Date: Mon, 11 Sep 2006 16:06:18 -0400
To: cxf-dev@incubator.apache.org

Hey Eric, aren't you the guy who appended "CeltiXfire" to the *end*  
of the *alphabetically-ordered* list of projects displayed on the  
right side of <http://incubator.apache.org>? On that basis alone, I  
think this argument goes to Dan... ;-)

--steve

On Sep 8, 2006, at 3:41 PM, Johnson, Eric wrote:

>
>
>> -----Original Message-----
>> From: Dan Diephouse [mailto:dan@envoisolutions.com]
>> Sent: Friday, September 08, 2006 12:14 PM
>> To: cxf-dev@incubator.apache.org
>> Subject: Re: Wiki and Web
>>
>>
>>
>> Johnson, Eric wrote:
>>
>>> Dan,
>>> In terms of developing a Web site, and documentation, it appears we
> are
>>> coming at this from different points of view. From my point of view
> as
>>> someone whose focus is on documentation, messaging, and Web design
>>> taking an hour to polish up a Web page or a piece of  
>>> documentation is
>>> not an egregious burden. I would imagine that you spend as much
> effort
>>> testing the code base before releasing it. A professional Web site
>>> should not need to be updated on a daily basis. It, like the  
>>> released
>>> version of a product, should be well tested and reviewed before  
>>> being
>>> published. This does make it more difficult to make updates to the
> site,
>>> but it also ensures that updates are well thought out and vetted
> before
>>> being made.
>>>
>>>
>> I disagree. First, I don't actually believe that this is how
>> documentation is created. Often a release is pushed out and then
>> documentation is written. Documentation has a life of its own beyond
>> just the initial release.
>
> Having worked as a doc writer for a number of years, I have never  
> seen a
> release pushed out with out documentation. The documentation often  
> does
> get improved after the initial release, but it is solid before  
> hand. My
> experience is entirely based on working for a company that wants to  
> sell
> software, not an open source project however.
>
>> Second, I am of the philosophy that documentation should be part of
> the
>> continuous improvement cycle of the project and it is impossible to
>> separate out from developing and support of users. For instance, with
> I
>> read the xfire user's list and a question comes up that isn't
> addressed
>> in the docs, I go and write something, then point users to it. Or I
>> write a response and ask users to add to the docs. (a lot of times
> they
>> even do a really thorough job).
>>
>> I think the wikipedia provides a great example. It goes through
>> continuous improvement and people watch it religiously for any
>> backtracks. This makes documentation much more agile and makes it  
>> much
>> more open/approach to others.
>
> I too think that documentation is an ongoing process and as people  
> come
> up with new issues, use cases, and other suggestions for  
> improvement the
> documentation should be updated. I also like the idea that any user  
> can
> add information about the product. However, I also think that you need
> to have both a place where user supplied information can live and a
> separate place where documentation that has been reviewed, vetted, and
> given an official stamp of approval lives. Most teachers I know would
> not accept Wikipedia as a valid reference for information simply  
> because
> it does not have a strict review process. I'm going to go out on a  
> limb
> and guess that most major companies, who we hope are going to use
> CeltiXfire, are not going to accept documentation that is on a wiki as
> sufficient.
>
>>
>>> The same would go for versioned, official documentation. The source
>>> should be stored in the project trunk with the code and built as  
>>> part
> of
>>> the project. When a version of the product is released, the vetted
> and
>>> reviewed documentation can be packaged and delivered as part of the
>>> download. It can then also be pushed out to the Web site.
>>>
>>>
>> I disagree that documentation should be so strictly version with the
>> project as it often continues to improve outside of the release  
>> cycle.
>> Docs are never done.
>>
> How do you keep the documentation aligned with releases? What if an
> outside entity, such as IONA, wants to consume and repackage the
> documentation for a particular release?
>
>>> This does not preclude a developer from documenting a new  
>>> feature, or
>>> adding supplemental documentation, through the wiki. In fact,  
>>> that is
>>> probably the best place for it.
>>>
>> Why is that the best place? It is outside the normal docs and harder
> to
>> find,
>>
> It does not have to be harder to find, but it does mean that it is
> clearly placed outside of the official set of documentation.
>
>>> If the community feels that information
>>> on the wiki should be moved into the official documentation, then a
> task
>>> can be submitted and the work can be done to make that happen. If
> not,
>>> then it can stay on the wiki. Links can be added to the main page to
>>> make such forms of documentation easily accessible.
>>>
>>> Here is what I propose:
>>> 1. The main Web site for the project is done in HTML. This means
> anybody
>>> with HTML knowledge can make updates.
>>> 2. The Web site is only republished when there is a need to  
>>> update it
>>> and the community, or an elected member of the community, has
> reviewed
>>> the content.
>>> 3. The main Web site has at least one link to the Wiki where people
> are
>>> free to add FAQ's, documentation, and other stuff. If something  
>>> there
>>> meets muster, a link to it can be added to the main site or the
> content
>>> can be ported to the main site.
>>> 4. If project members have blogs or other links they want published
>>> those too can be added to the main site if the community thinks  
>>> it is
>>> appropriate.
>>> 5. Official, versioned documentation is written using DocBook XML  
>>> 4.2
>>> and the source is stored in the trunk along with the code.
>>> 6. The official, versioned documentation is built along with the  
>>> code
>>> and is part of the official product release.
>>> - There are open-source XSLT stylesheets that can be used to build
> nice
>>> looking, customizable HTML and PDF output from this source.
>>> 7. Other documentation can be written on the wiki. If the community
>>> thinks it belongs in the official set, it can be ported.
>>>
>>>
>> I've thought long and hard about this, but I'm -1. I think we should
> do
>> it all in the wiki. Many projects do it (for instance Dojo uses
> JotSpot)
>> and it works very well. I think doing it all in the wiki is more
>> inclusive, agile, and community focused.
>
> All in all I agree that a wiki is a great way to encourage community
> contribution and provides a fast way to get content produced. However,
> they also present problems such as versioning, image, structure,
> indexing, navigability... Once you get beyond a few bits of
> documentation, a Wiki can get cumbersome to navigate. They also, in my
> opinion, lack a certain amount of credibility and professionalism. The
> Apache Web server and Tomcat don't use wikis for their docs and I  
> doubt
> their users would be pleased if they decided to switch to a wiki.
>
>>
>> Cheers,
>>
>> - Dan
>>
>> --
>> Dan Diephouse
>> (616) 971-2053
>> Envoi Solutions LLC
>> http://netzooid.com
>
>