Help:Style guide: Difference between revisions

Latest revision as of 21:16, 19 July 2011

For the other style guides, see Help:Wiki syntax and markup.

This style guide is a collection of best practices for articles on the Fedora Project Wiki that encourage clarity and consistency. Wikipedia's Manual of Style serves as the guide for most style decisions, so this guide focuses greater on areas that are specific to Fedora.

Titles

An article title should very briefly describe the content of its article. The title should be a noun, and it should be singular unless the article is explicitly discussing the plural form. The article name should not be a sentence, nor should it be an abbreviation. It should almost never include an article prefix. Only the first word of an article title should be capitalized unless the article is discussing a proper noun.

When writing links to other articles, separate the words of both the article title and the piped content with spaces; underscores should never be used as, internally to the wiki, they are identical to spaces.

Section titles

Section titles follow similar rules to article titles. Section titles should briefly describe their section's content, they should only have their first word capitalized (unless otherwise required), and they should usually not be in the form of a sentence or question. Section titles should not contain links.

Section titles should be omitted unless necessary. The first section of an article should never be named "Summary", "Overview", or "Introduction" as this is assumed - place such content at the top of the page before any section definitions. Sections should not be used sections unless there is a sufficient need to distinguish topics; for small variations in the subjects, paragraphs are more natural

Editing

Abbreviations should only be used if the abbreviation is more common than the unabbreviated name. For example, QA is more recognizable in the community 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.

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

Admonitions should be used very sparingly for regular articles. They should either provide information about the article (at the top of the page), or they should provide critical information regarding some issue. Tutorials and other types of articles may use these more regularly.

If a page is different enough from the regular scope of the wiki, you should make it apparent in the page title, but don't step outside the guidelines to do it. Some suggestions:

Instead of Drafts/Wiki policy, use Wiki policy (draft)
Instead of Proposal/No Frozen Rawhide, just use No Frozen Rawhide, and note that it's a proposal
Instead of HowTos/LiveUSB, use How to create and use Live USB

Referring to "Fedora"

The prefix "Fedora" should only be included for clarity or when discussing an official name. Articles like Fedora release criteria do not need the "Fedora" since that relationship is implied by the fact that it's on this wiki.

Specific versions of Fedora should be referred to by their full name, like "Fedora 13". Fedora Core versions should always be referred to as "Fedora Core 4", and never "Fedora 4". Abbreviating to "F13" and "FC4" is acceptable. (Remember that "Fedora Core" changed to "Fedora" between Fedora Core 6 and Fedora 7.)

"Fedora Project" is the proper way to refer to this community. This website should be referred to as fedoraproject.org.

Refer to Logo/UsageGuidelines for information on using the Fedora logo.

Organizing content

Categories should be used to group members of a larger group, such as Ambassadors. Do not use article prefixes.

Subtopics should be contained in either sections or 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

Remember to think of a category structure like a tree: subcategories are branches, pages are leaves. If a branch has too many leaves, the branch gets too heavy, breaks off the tree, and falls to the ground. Subcategorize categories with too many pages.

Exceptional article types

Meeting logs should either be linked to logs on meetbot.fedoraproject.org or should be in the Meeting: namespace. 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 should not fall under any prefix, unless they are FUDCons. If an event is a FUDCon, use the FUDCon: namespace. The FUDCon: namespace allows any person to edit whether they are logged in or not.

Proposals may have "(draft)" at the end of their titles.

Tutorials, how-tos, and guides should note what they are in the title, but should not use a specific 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.

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. (Features are a special exception to the prefix rule.)

Projects and 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 new contributors but should leave the full join process to another page.

FAQs

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

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.

@@ Line 1: / Line 1: @@
-{{Draft}}
+{{for|the other style guides|Help:Wiki syntax and markup|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. Even though this wiki is tightly focused and contains a diverse spectrum of content, it should not deviate from [http://en.wikipedia.org 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.
+This '''style guide''' is a collection of best practices for articles on the [[Fedora Project Wiki]] that encourage clarity and consistency. [http://www.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia's Manual of Style] serves as the guide for most style decisions, so this guide focuses greater on areas that are specific to Fedora.
-Let me address a few of the pressing concerns, and some of their potential solutions.
+== Titles ==
+An article title should very briefly describe the content of its article. The title should be a noun, and it should be singular unless the article is explicitly discussing the plural form. The article name should not be a sentence, nor should it be an abbreviation. It should almost never include an [[Help:article prefix|article prefix]]. Only the first word of an article title should be capitalized unless the article is discussing a proper noun.
-== Article prefixes ==
+When writing links to other articles, separate the words of both the article title and the piped content with spaces; underscores should never be used as, internally to the wiki, they are identical to spaces.
-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.''' 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.
+=== Section titles ===
-* '''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.
+Section titles follow similar rules to article titles. Section titles should briefly describe their section's content, they should only have their first word capitalized (unless otherwise required), and they should usually not be in the form of a sentence or question. Section titles should not contain links.
-* '''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.
+Section titles should be omitted unless necessary. The first section of an article should never be named "Summary", "Overview", or "Introduction" as this is assumed - place such content at the top of the page before any section definitions. Sections should not be used sections unless there is a sufficient need to distinguish topics; for small variations in the subjects, paragraphs are more natural
-=== Solutions ===
+== Editing ==
-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 ====
+Abbreviations should only be used if the abbreviation is more common than the unabbreviated name. For example, ''[[QA]]'' is more recognizable in the community 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.
-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:
-* <code>Log/</code> for meeting logs. Since these logs are not intended to be edited and have only one author.
+Tables should only be used for tabular content. Lists are usually less obtrusive ways to organize content.
-* <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.
-* <code>HowTo/</code> or <code>Tutorial/</code>. These describe a process in exact detail. They are linear and highly instructional.
-==== Categories ====
+Admonitions should be used very sparingly for regular articles. They should either provide information about the article (at the top of the page), or they should provide critical information regarding some issue. Tutorials and other types of articles may use these more regularly.
-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 ====
+<!-- I don't like this. :) Rewritten below --ianweller Tue Jun 23 02:52 UTC
-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:
+[[User:Dafrito/Article prefix|Article prefixes]], such as "Proposal/" in [[Proposal/No Frozen Rawhide]], should be used in cases where the nature of the content is different from regular wiki articles. Such instances are listed below. Most wiki articles should not use an article prefix.
+-->If a page is different enough from the regular scope of the wiki, you should make it apparent in the page title, but don't step outside the guidelines to do it. Some suggestions:
+* Instead of ''Drafts/Wiki policy'', use ''Wiki policy (draft)''
+* Instead of ''Proposal/No Frozen Rawhide'', just use ''No Frozen Rawhide'', and note that it's a proposal
+* Instead of ''HowTos/LiveUSB'', use ''How to create and use Live USB''
+=== Referring to "Fedora" ===
+The prefix "Fedora" should only be included for clarity or when discussing an official name. Articles like [[Fedora release criteria]] do not need the "Fedora" since that relationship is implied by the fact that it's on this wiki.
+Specific versions of Fedora should be referred to by their full name, like "Fedora 13". Fedora Core versions should always be referred to as "Fedora Core 4", and never "Fedora 4". Abbreviating to "F13" and "FC4" is acceptable. (Remember that "Fedora Core" changed to "Fedora" between Fedora Core 6 and Fedora 7.)
+<!-- Groups should never use Fedora in wiki titles; their official names are "Fedora QA" and "Fedora Infrastructure" but those aren't included in wiki titles. Removed because this is covered by the above. --ianweller
+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).
+-->"Fedora Project" is the proper way to refer to this community. This website should be referred to as fedoraproject.org.
+Refer to [[Logo/UsageGuidelines]] for information on using the Fedora logo.
+=== Organizing content ===
+Categories should be used to group members of a larger group, such as [[Ambassadors]]. Do not use article prefixes.
+Subtopics should be contained in either sections or separate articles. Their name should include the broader topic. For example, here's a layout for articles discussing releases :
 * Release
-** Release types
+** Types of releases
-*** Branched
+*** Branched, or Branched Release
-*** Rawhide
+*** Rawhide, or Rawhide Release
 ** 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.
+Remember to think of a category structure like a tree: subcategories are branches, pages are leaves. If a branch has too many leaves, the branch gets too heavy, breaks off the tree, and falls to the ground. Subcategorize categories with too many pages.
+== Exceptional article types ==
+* '''Meeting logs''' should either be linked to logs on [http://meetbot.fedoraproject.org/ meetbot.fedoraproject.org] or should be in the Meeting: namespace. 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''' should not fall under any prefix, unless they are FUDCons. If an event is a FUDCon, use the FUDCon: namespace. The FUDCon: namespace allows any person to edit whether they are logged in or not.
+* '''Proposals''' may have "(draft)" at the end of their titles.
+* '''Tutorials''', '''how-tos''', and '''guides''' should note what they are in the title, but should not use a specific 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.
+* '''Feature pages''' combine a proposal and an article. They should use a <code>Features/</code> 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. (Features are a special exception to the prefix rule.)
-== Section titles ==
+* '''Projects''' and '''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 new contributors but should leave the full join process to another page.
-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.
+FAQs collect a large number of questions and can be more efficient than articles.
 === Organization ===
@@ Line 55: / Line 82: @@
 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
+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.
 === 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.
+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.
-* 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 ===
+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.
-[[FAQ]] is not a bad FAQ. [[Shipping_fonts_in_Fedora_(FAQ)]] does not use section titles, and its content is extremely hard to skim.

Search