Post Hoary

Corey Burger corey.burger at gmail.com
Fri Mar 4 22:42:32 UTC 2005


On Fri, 4 Mar 2005 14:27:07 -0800, Jeff Schering <jeffschering at gmail.com> wrote:
> 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.

I think you misunderstand me here. The pdfs would be created by us and
shipped by us. If we have a consistent wiki markup, that would be
fairly easy to do.
> 
> 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.

Yes, but a good number of people need help fast, and wiki can easily
provide that. Likewise PDF's. All this would need to be tied into
froud's XUL toolbar that runs locally of course.

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

There is no reason a wiki page could not be converted to all those
forms. Remember wiki IS html.

> 
> 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
> 
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
> 

There are 2 kinds of barriers here
1. Barriers to contribute
For this barrier, svn and docbook do constitute, IMHO, a fairly high
learning curve. In addition to the learning curve, the barrier of
needing an extra program, etc.

2. Barriers to read/consume

I understand your concerns about various formats. However, it is just
text at the end of the day, and there is no reason why with a wiki
page as primary source, the various formats could not be created.

One further note.

IMNSHO, most computer docs are crap. They do not serve the needs of
the users. More well formatted but slow to write stuff only continues
this trend. Most people, especially new computer users, are very task
oriented. Current docs fail them horribly. If current docs worked, we
wouldn't need an FAQ section at ubuntuforums. And if docbook was easy,
ubuntuguide.org wouldn't exist.

Thus, we need (should? could?) change to a different form of producing
docs. If we need nice docbook crap, we can get it from
gnome/debian/tldp. People need docs written for people, task oriented.
These are fast and easy to produce, and the wiki facilitates that.
Wikis also allow really easy linking, so that more technical things
can be explained on other pages (theory of dns, dhcp, etc.)

Also, doc book tends to create very large documents. Smaller, bit
sized chunks are better, and this works better in a wiki environment.
Corey




More information about the ubuntu-doc mailing list