Ubuntuguide.org Considered Harmful

Tue Jun 5 16:17:36 UTC 2007

Whoops, should read:

2) Make information EASY to edit

The joys of spell check and the wrong word spelled correctly.

Aaron Kincer wrote:
> 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
>>>
>>>     
>>
>>   
>
>