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 <[EMAIL PROTECTED]> 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 >>> [email protected] >>> https://lists.ubuntu.com/mailman/listinfo/ubuntu-server >>> >>> >> >> > > -- ubuntu-server mailing list [email protected] https://lists.ubuntu.com/mailman/listinfo/ubuntu-server
