Ubuntuguide.org Considered Harmful

[Aaron Kincer]

It's no secret that documentation is the least sexy part of the 
technical realm. But it seems to me the way to encourage the group 
process and achieve accuracy (have your cake and eat it too) is to 
achieve as many of the following as possible:

1) Make information easy to find
2) Make information east to edit
3) Establish a "standard" way to write documentation so someone only has 
to drop in their steps in a template
4) Establish a rank system
5) Provide attribution


I listed those in the order that I think are most important. Finding 
information easily is the proverbial chicken (see Google for reference) 
and making it easy to edit is the egg (see Wikipedia). Providing a 
standard no-brainer way to display information is the next link in the 
chain (see Myspace). Lastly, providing attribution and a rank system 
complete the gambut (see Slashdot and Digg).

While an endeavor can be successful with having only one of those, the 
more you have, the better off you are. The standard template design I'm 
talking about doesn't have to be interface driven like Myspace even 
though I used that as an illustration. Although having a "wizard" type 
interface to guide someone would make it easier. Otherwise, people would 
have to emulate what others do and would require a cleanup crew to go 
back and massage entries that are a bit cavalier in their organization. 
If you think documentation isn't sexy, try cleaning up documentation.

Of course, implementing all of this is a huge endeavor. The immediate 
thing that can be done that doesn't require a tremendous effort is a 
more straight forward and organized wiki that allows people to be 
viewing and editing task oriented information in two clicks or less from 
the main wiki screen. I'm thinking:

Wiki main page -> Click on Feisty Server (or other version) Wiki

I think from there, it is not out of the question to have categories to 
select with a "View All" link at the top for those that have the 
bandwidth to pull it all at once and don't want to click through four 
links just to figure out how to configure dual head for their nVidia 
card. Maybe it would be more expedient just to skip the categories and 
have one main Wiki page for a version like UG does.

While the information in UG may not be relied upon to be completely 
accurate, there is a reason it is successful. My opinion is that it is 
quick and easy to find what you are looking for (accuracy aside).

Of course, the decision to make changes such as this does not rest in my 
hands and these are only my opinions.

Aaron Kincer

Jim Tarvid wrote:
> Merely true!
>
> I run across competing howtos all the time. The academic world
> addresses the issue by "journaling". That doesn't always work either.
> I use a sandbox approach and have reinstalled some things a dozen
> times or more before I get it exactly right.
>
> How do we encourage the group process of many eyes makes better documentation?
>
> Jim Tarvid
>
> On 6/5/07, Aaron Kincer <kincera at gmail.com> wrote:
>   
>> Kristian,
>>
>> I'm with you that not all the information there is "good" and can break
>> your system. Heck, I've seen some instructions there that were just
>> plain wrong without even having to try them out. However, in my opinion,
>> the layout of the UG is much better and easier to find information
>> quickly than the official wiki site you linked to. Until this is
>> addressed, I'm afraid there are some that will not go there first (maybe
>> even at all). In my opinion, there should be links at the very top to a
>> task oriented wiki similar to UG for each respective version. The links
>> at the bottom don't lead to help and are just confusing.
>>
>> When someone wants to know how to do something very specific, trying to
>> sort through the pages there is a bit cumbersome in my humble opinion.
>> When I have a very specific task I want to accomplish, I'd prefer not to
>> navigate through more than a couple of clicks.
>>
>> Aaron Kincer
>>
>>
>> Kristian Hermansen wrote:
>>     
>>> All,
>>>
>>> Be wary of Ubuntuguide.org.  When users first encountered it, they consider it
>>> to be a great resource.  Everything you might need to do is in one
>>> place with info how to accomplish a goal.  However, the problem is
>>> that using Ubuntuguide.org may result in your system becoming broken
>>> or incorrectly configured.  The guide is not always correct, and you
>>> may break your system, especially when it comes to upgrade to the next
>>> release of Ubuntu.  Much of this has to do with adding third party
>>> sources to your APT configuration.  When you do this, your system
>>> could be stable for a few months, until you decide to move to Gutsy,
>>> and then you wonder why Ubuntu
>>> fails to upgrade!
>>>
>>> Please please please use http://wiki.ubuntu.com or the other
>>> help/community resources at the official Ubuntu domain ahead of any
>>> other resource.  Once you realized that Ubuntuguide is harmful, make
>>> every effort to support the official wiki and add items there.  Some
>>> people on this list may not realize the harm that can be done if you
>>> add unofficial items to your APT sources.  This is one of the major
>>> issues with UG, as they are always suggesting you do this.  With
>>> Ubuntu,  you normally don't need to do this, since most software is in
>>> the hosted repositories.  Again, Ubuntuguide.org should be avoided at
>>> all times...
>>>
>>>       
>> --
>> ubuntu-server mailing list
>> ubuntu-server at lists.ubuntu.com
>> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
>>
>>     
>
>