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, 08 Sep 2006 16:14:03 GMT


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.

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.

>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.

>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,

>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.

Cheers,

- Dan

-- 
Dan Diephouse
(616) 971-2053
Envoi Solutions LLC
http://netzooid.com


Mime
View raw message