Post Hoary

[Jeff Schering]

On Fri, 4 Mar 2005 02:06:21 -0800, Corey Burger <corey.burger at gmail.com> wrote:
 
> I content that we should to the wiki as the primary source for all documents.
> 
> There are 2 primary reasons for it:
> 
> 1. Low barrier to entry to new people
> 2. Fast changes
> 

<snip>

> 
> Now rip me to shreds,
> 
> Corey
> 

Hi Corey

I won't rip you to shreds, but thanks for the invite! :-) 

Your main reasons for advocating wiki as primary source are ease of
participation and speed of revision. I would like to disagree. Here is
why:

You say that by having wiki as a primary source, it means that there
are fewer barriers to participation. I do not believe that statement
to be true. The biggest reason is that the wiki is available in one
place and one place only: the internet. Sure you can use the browser
to print a page for off-line reading, and some wikis have pdf
functionality, but that is insufficient. For one thing, the pdf output
(at least the one's I have seen) is not much different than the output
of the browser's print function. It also needs to be done one page at
a time; if you want to browse the paper docs on the train to work, you
have to visit each and every linked wiki page and print them out by
hand. Not easy, and certainly not fun.

Another reason why a wiki is not the best medium to have as a primary
source of written material: it is not presentation neutral. There is
not enough separation between content and presentation. Different
people access documentation in different ways. You'd be surprised how
many people print out their emails before reading them. The concept of
reading more than a few lines on screen is still foreign to many.

Some people are more comfortable printing out the documentation all at
one go as a pdf and then reading it off-line at their leisure. Some
people prefer to use html help, others want Yelp on Gnome, KDE has its
own help app, other people want to read it as one big html file so
they can use the browser's text search function, others want it as
html split up into many pages with TOC and index. Others have
difficulty seeing the screen, and need the text to be read by a
machine.

If you have only one method of access, then you create a barrier to
all those who cannot or will not use that method. When I write my
words, I want those words to be available to as many people as
possible. That means my words have to appear in all the different
presentation formats that people are using. Wiki markup cannot be
converted to all those different formats in a clean way because its
markup is not presentation neutral.

Docbook markup is xml. It is presentation neutral. It has an extremely
rich set of semantic markup elements (tags). You can create any
current documentation format imaginable, plus probably any future
format.

As for speed, a few people joined the project close to the Quick Guide
freeze date and made (and are still making) valuable contributions.
Docbook was not a barrier. Subversion was not a barrier. The ones who
did not have time to learn Docbook or svn simply posted their changes
to the list, and someone incorporated them. Sean and Enrico make sure
that if you have something to add, then it gets added. Posting to the
list is much easier than tracking down the right wiki page, learning
wiki markup, getting a wiki password, and then making the change.

I think the wiki has its place, but not as a primary source of
documentation content.

Cheers,
Jeff