-----Original Message-----
From: Dan Diephouse [mailto:[EMAIL PROTECTED]
Sent: Friday, September 08, 2006 12:14 PM
To: [email protected]
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
