Help:Style guide: Difference between revisions

Revision as of 16:16, 22 June 2010

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

I humbly think that the Fedora wiki deviates too often from common expectations, and it should be safely and carefully reorganized to adhere more with traditional practices. It should not deviate from the Wikipedia unless it has good reason to do so. Things like unusual article names, unconventional article formats, and unexpected uses of features confuse users and discourage contributors. I have proposed some policy for this wiki that I believe will make the wiki much easier to understand and much more consistent.

Article Naming Rules

An article name should very briefly describe the content of the article. It should be a noun, and it should be singular unless the article is specifically discussing the plural form of something. The article name should not be a sentence, nor should it be an abbreviation. It should almost never include an article prefix. Separate words in the name should be separated by underscores. Only the first word should be capitalized unless the article is discussing a proper noun.

If an article can never be directly linked - it must be piped to look presentable ( i.e., QA/Updates_Testing) - it's probably not a good article name.

Referring to "Fedora"

Fedora should only be included in article names if the article is discussing a proper noun, or if disambiguation is necessary between Fedora and some other distro. Articles like Fedora release criteria do not need the "Fedora" in the name since the wiki is obviously Fedora-related.

If an article is referring to release criteria for a specific version of Fedora, then that version should be included in the name. The abbreviation FC4, F12, etc. should never be used in any article, unless it is explicitly required (such as when referring to a package built for "fc13"). Fedora Core versions should always be referred to as "Fedora Core 4", and not "Fedora 4".

Fedora vs. Fedora Project

Both "Fedora" and "Fedora Project" are used in this wiki. "Fedora" should refer to the distro as both an adjective and a noun. The "project" in "Fedora project" should not be capitalized, as there is no corresponding "Fedora Project." This website should be referred to as fedoraproject.org.

Projects and groups, like QA, releng, etc. should only include "Fedora" if that's part of their official name, or if they need to disambiguate (Fedora QA versus some other QA).

Abbreviations

Abbreviations should be used if the abbreviation is more common than the unabbreviated name. For example, QA is more recognizable than Quality Assurance. Abbreviations should also be used if the official name of a group or project is an abbreviation, such as L10N. If so, that should be the only way used to refer to that group.

If none of those rules apply, the full name should be used.

Article prefixes

For why article prefixes are harmful, see User:Dafrito/Article prefix.

Article prefixes should be used in cases where the nature of the content is different from regular wiki articles. Such instances are listed below. Regular wiki articles should never use an article prefix.

Tables

Tables should only be used for tabular content.

Meeting and IRC Logs

All meeting logs should be named Logs/YYYYMMDD/QA_Meeting. The timezone used should be consistent for the meeting, and the name should not change from meeting to meeting. The meeting should also be a member of a category, so all meetings can be viewed quickly.

Events

Events should fall under a Event/ prefix. Policy for event pages is similar to user pages, with an implied owner.

Proposals

Proposals should fall under a Proposal/ prefix. Proposal discussion should occur within the talk page.

Subtopics

Articles that provide specialized insight into a broader topic should be contained in separate articles. Their name should include the broader topic. For example, here's a layout for articles discussing releases :

Release
- Release types
  - Branched
  - Rawhide
- Release criteria
- Release process

Section titles

Section titles should be relatively short, they should usually not be in the form of a sentence or question, and they should describe their section's content. Titles should not contain links.

FAQs

FAQs collect a large number of questions and can be more efficient than articles. I believe they have a definite purpose when organized properly.

Organization

FAQs should be arranged by questions. Each section should answer a single question, and that section's title should be the question. Longer FAQs should group questions by category. Each question group should have names that abide by the naming rules of a regular section. If the FAQ is still hard to skim, the FAQ should be broken into separate articles.

A FAQ should have a similar level of required expertise. FAQs should not bounce between basic and advanced questions, as this confuses readers. Sections should have a similar implied level of understanding. Advanced questions are usually best spent being rolled into another FAQ, article, or section.

If your questions are highly related, have a linear flow, and do not cover a broad range of topics, you may be better served by converting it to an article instead.

Questions

Questions should be independent of one another. A question should make sense on its own, and not be dependent on the question or answer that came before it. The question should be as short as possible, but also easy to read. If a question is difficult to word, it likely should be an article or tutorial.

A question should actually ask a question: things like "I can not comply, the tools my package uses force a specific font file installation!" require the user to guess as to the content contained within. Other questions such as "This is too much work!" verge on insulting to users, and should be removed entirely. Do no

Answers

Questions should have substantial answers. If an answer can only respond with a link to another article, then it probably should be expanded or the question reworded. However, if a 'Yes' or 'No' will do, then that's all the answer should have.
Questions should not be strive to be comprehensive. An answer should be sufficient for the question asked, but it should not be exhaustive. A response should provide enough information to answer the question, and link to other articles to provide more information.the answer can be short.

How-to style responses should generally be avoided, unless the answer is very short. Otherwise, the response should answer the question by briefly describing the process, and linking to a dedicated tutorial page.

Examples

FAQ is not a bad FAQ. Shipping_fonts_in_Fedora_(FAQ) does not use section titles, and its content is extremely hard to skim.

@@ Line 27: / Line 27: @@
 == 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:
+{{for|why article prefixes are harmful|User:Dafrito/Article prefix}}
-===Article prefixes are ambiguous===
+Article prefixes should be used in cases where the nature of the content is different from regular wiki articles. Such instances are listed below. Regular wiki articles should never use an article prefix.
-Article prefixes are usually too terse to indicate their purpose, or too generic to be useful. For example, the QA prefix does not indicate whether articles relate to the QA project, quality assurance in general, or articles that are merely relevant to QA. In reality, the prefix is used for all three of these purposes.
-===Article prefixes miscategorize content===
-Since prefixes are ambiguous, editors typically are unable to find a single prefix that wholly fits their article. Content gets spread over many different prefixes, and is not predictable or easily accessible. For example, [[Fedora Release Criteria]] discusses the criteria for Fedora releases. [[Releases]] discusses releases in a broad sense. [[ReleaseEngineering/Overview]] also discusses releases, but from a releng point of view. These articles should be merged or reorganized to complement each other, rather than compete.
-===Article prefixes are inconvenient===
-Article prefixes make it difficult for editors to link with existing articles. There is no definitive place for content, so very relevant articles end up in very strange, unpredictable places.
-These problems combine to create a confusing experience for users and editors. Contributors miss opportunities to network with existing content, and visitors are left confused and frustrated.
+== Tables ==
-=== Solutions ===
+Tables should only be used for tabular content.
-The majority of article prefixes should be deprecated and phased out. Redirects should remain to preserve backwards-compatibility, but the prefixed articles should not be directly reachable. The specific fix for a prefixed article depends on the original reason for the prefix and the article's content.
-==== Function-related articles ====
+== Meeting and IRC Logs ==
-Since prefixes imply a strong, mutually exclusive separation of purpose, they should be used when articles have special editing rules or unconventional origins. Here's a few examples of some good candidates:
+All meeting logs should be named <code>Logs/YYYYMMDD/QA_Meeting</code>. The timezone used should be consistent for the meeting, and the name should not change from meeting to meeting. The meeting should also be a member of a category, so all meetings can be viewed quickly.
-* <code>Log/</code> for meeting logs. Since these logs are not intended to be edited and have only one author.
+== Events ==
-* <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.
+Events should fall under a <code>Event/</code> prefix. Policy for event pages is similar to user pages, with an implied owner.
-* <code>HowTo/</code> or <code>Tutorial/</code>. These describe a process in exact detail. They are linear and highly instructional.
-==== Categories ====
+== Proposals ==
-Prefixes are sometimes used to imply a categorical relationship. These should be fixed by removing the prefix and adding the appropriate category. Prefixed articles like the many under the  [[Ambassadors]] prefix are ideal candidates.
+Proposals should fall under a <code>Proposal/</code> prefix. Proposal discussion should occur within the talk page.
-==== Subtopics ====
+== Categories ==
-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:
+Categories should be used to group members of a larger group, such as ambassadors.
+Article prefixes should never be used to group together categorically-related things.
+== Subtopics ==
+Articles that provide specialized insight into a broader topic should be contained in separate articles. Their name should include the broader topic. For example, here's a layout for articles discussing releases :
 * Release
@@ Line 60: / Line 58: @@
 ** 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 gracefully accomplished.
 == Section titles ==

Search