From Fedora Project Wiki

(→‎Contacts: Changed a mistaken org to net when referring to freenode)
(→‎Thoughts: Added lots of info regarding my thoughts on the wiki)
Line 18: Line 18:
== Thoughts ==
== Thoughts ==


* Shouldn't [[Fedora]] link to an article on Fedora, rather than the infrastructure page?
* Shouldn't [[Fedora]] link to an article on Fedora, rather than [[infrastructure]]?
* It'd also be cool to have pages for all versions of Fedora, with a template used to describe each.
* It'd also be cool to have pages for all versions of Fedora, with a template used to describe each.
* "updates-testing" and "Test Updates" are used interchangeably, which I don't believe should be the case. "Test Updates" is a natural name which succinctly describes its purpose. "updates-testing" is the technical name that is used by machines. This dual-naming scheme is familiar to the common and scientific names given to animals, like ''Canis lupus'' referring to a wolf, and I think the expectations for which to use for animal names should apply here.
* "updates-testing" and "Test Updates" are used interchangeably, which I don't believe should be the case. "Test Updates" is a natural name which succinctly describes its purpose. "updates-testing" is the technical name that is used by machines. This dual-naming scheme is familiar to the common and scientific names given to animals, like ''Canis lupus'' referring to a wolf, and I think the expectations for which to use for animal names should apply here.
* I really like the headers for Wiki pages here. They're very nice looking. My only problem is that they imply a gated community; QA pages seem to be 'owned' by QA. This is reinforced by the fact that they're under the QA/ namespace. It seems like there could be a better solution for this sort of thing, like making these headers be footers, like a decorated Wiki category.
 
== State of the Fedora wiki ==
Wiki's are excellent for housing lots of content, they are easy for people to edit and use, and they are well-understood. People have learned how Wikipedia.org is organized, and I believe they have come to expect Wikipedia-like behavior from similar looking sites. I humbly believe that the Fedora wiki deviates too often from this expectation, and I think an effort should be made to reorganize it, safely and carefully, to adhere more with common conventions.
 
I understand that the Fedora Wiki has a different purpose than the Wikipedia itself. Along with housing purely encyclopedic articles, it houses drafts, proposals, how-to's, meeting logs, project homepages, and so on. I think this is an excellent use of the wiki, as it can tolerate a vast amount of information without overloading users. The Fedora wiki should not deviate from user's expectations unless there is a great benefit from the deviation. Things like unusual article names, unconventional article formats, and unexpected uses of features are sadly the norm in the wiki. I believe these inconsistencies cause confusion amongst visitors and discouragement amongst contributors. Let me address a few of the pressing concerns, and some of their potential solutions.
 
=== Article prefixes ===
Article prefixes are pseudo-categories that mangle article names, such as the <code>QA/</code> in [[QA/Updates Testing]]. While prefixes can sometimes appear natural, such as [[Releases/Rawhide]], they are usually unnecessary and distracting. For the most part, articles that have prefixes would be better served by either being in a category, by having a more descriptive name, or not having a prefix whatsoever. Article prefixes are harmful to the Wiki in many ways:
 
* Article prefixes are ambiguous. [[QA/Updates Testing]] is an ambiguous, and probably inappropriate name. The implication is that the article provides QA-specific information on <code>updates-testing</code>, or that <code>updates-testing</code> is something that is owned/managed/created by QA. Neither is true: the linked article is the only article that discusses this repository.
* Article prefixes are arbitrary. [[Fedora Release Criteria]] discusses the criteria for Fedora releases. [[Releases]] discusses releases in a broad sense. [[ReleaseEngineering/Overview]] is a very good article that also discusses releases. All are good, but which is definitive? There should be a natural starting point to these articles, with specific content in specifically named articles.
* Article prefixes appear to already be deprecated. Many, many articles that have prefixes redirect to unprefixed names. If this is the case, there should be a policy that they are to be entirely phased out. Redirects should remain, of course, but they should not be reachable from current articles.
* Article prefixes create walled gardens. <code>QA/</code> appears to "own" many articles. This means that new articles that are related to QA-owned ones should also be in the QA prefix. This causes the QA prefix to become more vague in its meaning as more articles are included. The alternative means that some related content lies uses another prefix. This uncertainty creates confusion for new users.
* Article prefixes force piping. A contributor must type out the name, and then pipe it for easy readability such as <nowiki>[[QA/Updates Testing|updates-testing]]</nowiki>. Their alternative is not piping and instead having the unsightly [[QA/Updates Testing]]. This is an unnecessary frustration.
* Article prefixes are almost always unnecessary. Categories are already the conventional means to group content, not prefixes. Categories also allow an article to live in multiple groups. Categories also do not mangle article names and therefore allow safe and easy linking internally and externally.
 
These problems combine to create a confusing experience for both users and contributors. Visitors do not understand why a prefix is used, and contributors create redundant articles and neglect networking with articles of similar content. This severely hinders usability, since effort and articles are fragmented across arbitrary divisions.
 
==== Solutions ====
===== Function-related articles =====
Prefixes imply a strong, mutually exclusive separation of purpose or content from regular articles. Prefixes should be used when articles have special editing rules or if they have an unconventional origin. Here's a few examples:
 
* <code>Log/</code> for meeting logs. Since these logs are not intended to be edited and have only one author, they're ideal candidates for a special prefix.
* <code>Proposal/</code> for FESCo and other proposals. Proposals usually are much more fluid than regular articles. They typically have a strict format, are "owned" by an individual user, and document a "current" event rather than a concept or component in Fedora. This special nature deserves a prefix of its own.
* <code>HowTo/</code> or <code>Tutorial</code>. These describe a process in exact detail. They are linear and highly instructional.
 
===== Categories =====
Prefixes are sometimes used to imply a categorical relationship. These are easily fixed: remove the prefix and add the appropriate category. Prefixes like [[Ambassadors]] are ideal candidates for this fix.
 
===== Subtopics =====
Prefixes sometimes indicate a collection of subtopics. [[Releases]], [[Fedora Release Criteria]], and the content of [[ReleaseEngineering/Overview]] are all discussing one major concept: releases. These articles should be merged and renamed accordingly to indicate this topic/subtopic relationship. The following outline is a possibility:
 
* Release
** Release types
*** Branched
*** Rawhide
** Release criteria
** Release process
 
These subtopics could be sections in the "Release" article, or they could be separate articles referred to by the main article. This choice depends on the amount of content. Once again, the Wikipedia provides good examples for how this separation may be accomplished.[http://en.wikipedia.org/wiki/United_States]

Revision as of 18:53, 21 June 2010

My name is Aaron Faanes. I am a Fedora 13 user, occasional Wiki contributor, and frequent hacker. See my homepage.

Contacts

Email: dafrito@gmail.com

You can also find me on IRC. My nickname there is, not surprisingly, dafrito. I frequent many of the various Fedora channels on irc.freenode.net, such as:

  • #fedora
  • #fedora-qa
  • #fedora-devel
  • #fedora-bugzappers

Notable pages

Thoughts

  • Shouldn't Fedora link to an article on Fedora, rather than infrastructure?
  • It'd also be cool to have pages for all versions of Fedora, with a template used to describe each.
  • "updates-testing" and "Test Updates" are used interchangeably, which I don't believe should be the case. "Test Updates" is a natural name which succinctly describes its purpose. "updates-testing" is the technical name that is used by machines. This dual-naming scheme is familiar to the common and scientific names given to animals, like Canis lupus referring to a wolf, and I think the expectations for which to use for animal names should apply here.

State of the Fedora wiki

Wiki's are excellent for housing lots of content, they are easy for people to edit and use, and they are well-understood. People have learned how Wikipedia.org is organized, and I believe they have come to expect Wikipedia-like behavior from similar looking sites. I humbly believe that the Fedora wiki deviates too often from this expectation, and I think an effort should be made to reorganize it, safely and carefully, to adhere more with common conventions.

I understand that the Fedora Wiki has a different purpose than the Wikipedia itself. Along with housing purely encyclopedic articles, it houses drafts, proposals, how-to's, meeting logs, project homepages, and so on. I think this is an excellent use of the wiki, as it can tolerate a vast amount of information without overloading users. The Fedora wiki should not deviate from user's expectations unless there is a great benefit from the deviation. Things like unusual article names, unconventional article formats, and unexpected uses of features are sadly the norm in the wiki. I believe these inconsistencies cause confusion amongst visitors and discouragement amongst contributors. Let me address a few of the pressing concerns, and some of their potential solutions.

Article prefixes

Article prefixes are pseudo-categories that mangle article names, such as the QA/ in QA/Updates Testing. While prefixes can sometimes appear natural, such as Releases/Rawhide, they are usually unnecessary and distracting. For the most part, articles that have prefixes would be better served by either being in a category, by having a more descriptive name, or not having a prefix whatsoever. Article prefixes are harmful to the Wiki in many ways:

  • Article prefixes are ambiguous. QA/Updates Testing is an ambiguous, and probably inappropriate name. The implication is that the article provides QA-specific information on updates-testing, or that updates-testing is something that is owned/managed/created by QA. Neither is true: the linked article is the only article that discusses this repository.
  • Article prefixes are arbitrary. Fedora Release Criteria discusses the criteria for Fedora releases. Releases discusses releases in a broad sense. ReleaseEngineering/Overview is a very good article that also discusses releases. All are good, but which is definitive? There should be a natural starting point to these articles, with specific content in specifically named articles.
  • Article prefixes appear to already be deprecated. Many, many articles that have prefixes redirect to unprefixed names. If this is the case, there should be a policy that they are to be entirely phased out. Redirects should remain, of course, but they should not be reachable from current articles.
  • Article prefixes create walled gardens. QA/ appears to "own" many articles. This means that new articles that are related to QA-owned ones should also be in the QA prefix. This causes the QA prefix to become more vague in its meaning as more articles are included. The alternative means that some related content lies uses another prefix. This uncertainty creates confusion for new users.
  • Article prefixes force piping. A contributor must type out the name, and then pipe it for easy readability such as [[QA/Updates Testing|updates-testing]]. Their alternative is not piping and instead having the unsightly QA/Updates Testing. This is an unnecessary frustration.
  • Article prefixes are almost always unnecessary. Categories are already the conventional means to group content, not prefixes. Categories also allow an article to live in multiple groups. Categories also do not mangle article names and therefore allow safe and easy linking internally and externally.

These problems combine to create a confusing experience for both users and contributors. Visitors do not understand why a prefix is used, and contributors create redundant articles and neglect networking with articles of similar content. This severely hinders usability, since effort and articles are fragmented across arbitrary divisions.

Solutions

Function-related articles

Prefixes imply a strong, mutually exclusive separation of purpose or content from regular articles. Prefixes should be used when articles have special editing rules or if they have an unconventional origin. Here's a few examples:

  • Log/ for meeting logs. Since these logs are not intended to be edited and have only one author, they're ideal candidates for a special prefix.
  • Proposal/ for FESCo and other proposals. Proposals usually are much more fluid than regular articles. They typically have a strict format, are "owned" by an individual user, and document a "current" event rather than a concept or component in Fedora. This special nature deserves a prefix of its own.
  • HowTo/ or Tutorial. These describe a process in exact detail. They are linear and highly instructional.
Categories

Prefixes are sometimes used to imply a categorical relationship. These are easily fixed: remove the prefix and add the appropriate category. Prefixes like Ambassadors are ideal candidates for this fix.

Subtopics

Prefixes sometimes indicate a collection of subtopics. Releases, Fedora Release Criteria, and the content of ReleaseEngineering/Overview are all discussing one major concept: releases. These articles should be merged and renamed accordingly to indicate this topic/subtopic relationship. The following outline is a possibility:

  • Release
    • Release types
      • Branched
      • Rawhide
    • Release criteria
    • Release process

These subtopics could be sections in the "Release" article, or they could be separate articles referred to by the main article. This choice depends on the amount of content. Once again, the Wikipedia provides good examples for how this separation may be accomplished.[1]