Post Hoary

[Corey Burger]

More on wikis:

Watchlists are pages that allow you to chose a subsection of the wiki
to watch for changed. Basically a filtered recent changes. Thus, I
don't really care about anything but my wiki project Airports, so only
watch airports.

Rss and email feeds of said watchlists would be great. These dont
exist in WP yet.

As for page parenting, I find it very counter intuitive and rigid.
Wikis allow really easy linking. Categories are far more flexible.
Categories essentially allow a page to have several "parents", the
categories.

ie. A page about soup could be categorized into liquids and food.

As for dev time, I think if the doc team said that that is what we
wanted to do and produced specific things that needed to be done, I
think it would get done.

Corey


On Fri, 4 Mar 2005 14:42:32 -0800, Corey Burger <corey.burger at gmail.com> wrote:
> 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
>