Help:Style guide

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

For the current style guide, see Help:Wiki structure.

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. I have proposed some policy for this wiki that I believe will make the wiki easier to understand and more consistent.

The Wikipedia serves as a good example for most style decisions, so this guide focuses on areas that are specific to Fedora. For example, there are guidelines on FAQs, proposals, and info and alert blurbs.

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.

• Good: Fedora, Proven tester, Package maintainer, comps.xml
• Bad: How to use and edit comps.xml for package groups, L10N, PackageMaintainers/CVSAdminProcedure

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.

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.

Section titles should not be used if they are redundant. For example, "Summary" or "Overview" titles for the first section are redundant.

Tables

Tables should only be used for tabular content. Lists or infoboxes are usually less obtrusive ways to organize content.

Info blurbs, alert blurbs

This should be used very sparingly for regular articles. They should either provide meta-information on the article, or provide critical information regarding some issue.

Tutorials and other types of articles may use these more commonly.

Article prefixes

For why I feel 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.

Categories

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
  • Types of releases
    • Branched, or Branched Release
    • Rawhide, or Rawhide Release
  • Release criteria
  • Release process

Exceptional article types

Some article types are acceptable in the Fedora wiki that would not be accepted in the Wikipedia. These types follow special rules to differentiate their content and ensure consistency.

The type of an article should be mutually exclusive. Articles should never provide substantial amounts of unusual content on a single page.

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.

Meeting logs should not be edited or cleaned up. Relevant decisions and progress should be summarized and merged into existing articles.

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.

Guides

Tutorials, how-tos, and guides should fall under a Guide/ prefix. They should be specific, linear, and instructional. They should describe their purpose, their results, and their side effects. They may use second-person, but they should not be personal. They should provide wiki links to areas of interest, as applicable; they should not provide information that would be better suited for an article.

FAQS

FAQs are described in greater detail below.

Features

Feature pages combine a proposal and an article. They should use a Features/ prefix. Features should eventually become regular articles. The proposal should be separated from the content, and the feature can eventually serve as the article for whatever feature is being discussed.

Project or group pages

Project/group pages should either be portals or articles, but not both.

If they're portals, then they should be much shorter and link to a large number of related articles; they should behave like websites for that group.

If they are articles, they should describe the group. They should not use second-person. They can solicit users, but they should not emphasize that role.

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.

For a decent example, see Fedora's FAQ. For an example that doesn't fit this policy, see Shipping fonts in Fedora (FAQ).

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

Responses should be sufficient. They should provide links for more information if applicable. They should not be exhaustive, and do not need to be long; long answers are generally worse than a simple 'Yes' or 'No'. Provide a general, but sufficient response to the question, and provide links so the user to explore the issue on his own.

If the answer describes a process, it should be very short. How-to or tutorial-like responses should be converted into articles. The answer should summarize the process and the reason for performing it, and link to the new tutorial page.