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.

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. Even though this wiki is tightly focused and contains a diverse spectrum of content, 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.

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. 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.

Solutions

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

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:

• Log/ for meeting logs. Since these logs are not intended to be edited and have only one author.
• 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.
• 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 should be fixed by removing the prefix and adding the appropriate category. Prefixed articles like the many under the Ambassadors prefix are ideal candidates.

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 gracefully accomplished.

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.

FAQs

FAQs are not regular wiki articles. They collect a large number of questions and can be more efficient than articles.

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.