Difference between revisions of "MythTV Official Wiki:Manual of Style"

From MythTV Official Wiki
Jump to: navigation, search
m (External Linking: lc)
 
(45 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{inuse}}
 
 
 
{{style-guideline}}
 
{{style-guideline}}
  
Line 6: Line 4:
 
Also, we should keep the manual simple and straightforward, with anything ''too'' hairy (table styles, for instance) relegated to a linked page.-->
 
Also, we should keep the manual simple and straightforward, with anything ''too'' hairy (table styles, for instance) relegated to a linked page.-->
  
This '''Manual of Style''' has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules do not claim to be the last word on MythTV style. One way is often as good as another, but if everyone does it the same way, MythTV will be easier to read and use, not to mention easier to write and edit. In this regard, the following quotation from ''The Chicago Manual of Style'' deserves notice:
+
This '''Manual of Style''' has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules do not claim to be the last word on MythTV wiki-style. One way is often as good as another, but if everyone does it the same way, the MythTV wiki will be easier to read and use, not to mention easier to write and edit. In this regard, the following quotation from ''The Chicago Manual of Style'' deserves notice:
 
:Rules and regulations such as these, in the nature of the case, cannot be endowed with the fixity of rock-ribbed law. They are meant for the average case, and must be applied with a certain degree of elasticity.
 
:Rules and regulations such as these, in the nature of the case, cannot be endowed with the fixity of rock-ribbed law. They are meant for the average case, and must be applied with a certain degree of elasticity.
  
Clear, informative, and unbiased writing is always more important than presentation and formatting. Writers are ''not'' required to follow all or any of these rules: [[Wikipedia:Editing policy|the joy of wiki editing]] is that perfection is not required.
+
Clear, informative, and unbiased writing is always more important than presentation and formatting. Writers are ''not'' required to follow all or any of these rules: the joy of wiki editing is that perfection is not required.
  
 +
<div style="border: solid 1px; border-color: blue; margin: 1em; padding: 1em; background-color: lightblue; font-size: 80%">
 +
Note that this Style Manual was stolen bodily from Wikipedia; there will certainly be things we'll need to change, as we have differering requirements than they do.  Above all, remember The Wiki Way: try not to be offended if someone (particularly someone like [[User:Isaac|Isaac]], [[User:TylerDrake|Tyler]], [[User:Dan.littlejohn|Dan]], [[User:Kkuphal|Kevin]], [[User: DavidGreaves|David]], [[User:Steveadeff|Steve]], [[User:Gregturn|Greg]], or [[User:Baylink|myself]]) makes a change to a style or policy item you've contributed to.  Wiki's are all about everyone contributing, but someone does occasionally have to herd the cats.  :-)
 +
</div>
 +
<br>
 
==Article titles==
 
==Article titles==
 
If possible, make the title the ''subject'' of the first sentence of the article (as opposed to putting it in the predicate). For example, write "This Manual of Style is a style guide" instead of "This style guide is known as the Manual of Style."  In any case, the title should appear as early as possible in the article &mdash; preferably in the first sentence.
 
If possible, make the title the ''subject'' of the first sentence of the article (as opposed to putting it in the predicate). For example, write "This Manual of Style is a style guide" instead of "This style guide is known as the Manual of Style."  In any case, the title should appear as early as possible in the article &mdash; preferably in the first sentence.
Line 22: Line 24:
  
 
Follow the normal rules for italics in choosing whether to put part or all of the title in italics.
 
Follow the normal rules for italics in choosing whether to put part or all of the title in italics.
 +
 +
=== Singular vs. Plural ===
 +
It is better to name an article in the singular instead of plural notation, because it is easier to add plurality later in a sentence instead of removing it with a pipe.
 +
 +
<pre>[[Video Capture Card]]s</pre> is easier to maintain than <pre>[[Video Capture Cards|Video Capture Card]]</pre>
 +
 +
=== Upper case/lower case/mixed case ===
 +
Mediawiki automatically "uppers" article names. Every letter after the first, however, is case sensitive. To make your articles easier to link inline to those of others, use lowercase for the rest of the article unless it is a proper noun.
 +
 +
What you type:
 +
 +
{| border="1" cellpadding="2" cellspacing="0"
 +
! What it looks like !! What you type
 +
|-
 +
| For example, it is easier to link to a sentence about [[scheduling recording]]s than to link to one about [[Scheduling Recordings|scheduling recordings]].
 +
| <pre><nowiki>
 +
For example, it is easier to link to a
 +
sentence about [[scheduling recording]]s
 +
than to link to one about
 +
[[Scheduling Recordings|scheduling recordings]].
 +
</nowiki></pre>
 +
|}
 +
 +
''P.S. The singular rule would also be good in this case.''
  
 
==Headings==
 
==Headings==
 
 
Use the <tt>==</tt> (two equal signs) style markup for headings, not the <nowiki>'''</nowiki> (triple apostrophes) used to make words appear '''bold''' in  [[How_to_edit_a_page#Character_formatting|character formatting]]. Start with "<tt>==</tt>", add the heading title, then end with "<tt>==</tt>".  
 
Use the <tt>==</tt> (two equal signs) style markup for headings, not the <nowiki>'''</nowiki> (triple apostrophes) used to make words appear '''bold''' in  [[How_to_edit_a_page#Character_formatting|character formatting]]. Start with "<tt>==</tt>", add the heading title, then end with "<tt>==</tt>".  
  
Capitalize the first letter only of the first word and of any proper nouns in a heading, and leave all of the other letters in lower case.
+
Capitalize only the first letter of the first word or the first letter of any proper nouns in a heading, and leave all other letters in lowercase.
  
 +
Also note the following:
 
*Avoid links within headings.   
 
*Avoid links within headings.   
 
*Avoid overuse of sub-headings.
 
*Avoid overuse of sub-headings.
*Avoid "The" in headings, use: "Voyage" instead of "The voyage".
+
*Avoid "The" in headings.  For example, use "Voyage" instead of "The voyage".
*Avoid repeating the article title in the heading, use "Voyage" instead of "Voyage of the Mayflower" in an article titled "Mayflower".
+
*Avoid repeating the article title in the heading. For example, use "Voyage" instead of "Voyage of the Mayflower" in an article titled "Mayflower".
 +
*In general, avoid level 1 headings '='; they tend to stand out ''too'' much in the flow of a page. Tables of contents will be numbered based on the lowest numerical level heading, so they will not look silly.
  
 
==Capital letters==
 
==Capital letters==
Line 48: Line 75:
  
 
However, they do not start with a capital letter when they are used generally: "This summer was very hot."
 
However, they do not start with a capital letter when they are used generally: "This summer was very hot."
 +
 +
===As Of dates and versions===
 +
If you're talking about a feature that now exists "as of" a specific version, please put ''as of 0.19'' (or whatever version it may be, and wiki-link it.  This will permit us to go to that page, and check What Links Here, to find out what things need to be updated as new versions are released.  This is not necessary in the User Manual; it's expected that that section will be maintained as up-to-date as possible as new releases come out.
  
 
==Italics==
 
==Italics==
Line 63: Line 93:
 
   
 
   
 
===Titles===
 
===Titles===
 
 
''Italics'' should be used for titles of the following:
 
''Italics'' should be used for titles of the following:
 
*Books
 
*Books
Line 94: Line 123:
 
<blockquote>Now cracks a noble heart. Good night sweet prince: And ''flights of angels'' sing thee to thy rest!</blockquote>
 
<blockquote>Now cracks a noble heart. Good night sweet prince: And ''flights of angels'' sing thee to thy rest!</blockquote>
 
(emphasis added).
 
(emphasis added).
 +
 +
You can do the indentation either using HTML's &lt;blockquote> tag, or by indenting the paragraph on a ":".
  
 
==Punctuation==
 
==Punctuation==
Line 99: Line 130:
  
 
===Quotation marks===
 
===Quotation marks===
With [[quotation marks]], we split the difference between American and British usage. Though not a rigid rule, we use the "double quotes" for most quotations&mdash;they are easier to read on the screen&mdash;and use 'single quotes' for nesting quotations, that is, "quotations 'within' quotations".
+
With quotation marks, we split the difference between American and British usage. Though not a rigid rule, we use the "double quotes" for most quotations&mdash;they are easier to read on the screen&mdash;and use 'single quotes' for nesting quotations, that is, "quotations 'within' quotations".
  
:'''Note:''' if a word or phrase appears in an article with single quotes, such as 'abcd', the [[Wikipedia:Searching]] facility considers the single quotes to be part of the word and will find that word or phrase only if the search string is also within single quotes. (When trying this out with the example mentioned, remember that this article is in the Wikipedia namespace.) Avoiding this complication is an additional reason to use double quotes, for which the difficulty does not arise. It may even be a reason to use double quotes for quotations within quotations.
+
:'''Note:''' if a word or phrase appears in an article with single quotes, such as 'abcd', the Searching facility considers the single quotes to be part of the word and will find that word or phrase only if the search string is also within single quotes. (When trying this out with the example mentioned, remember that this article is in the Wikipedia namespace.) Avoiding this complication is an additional reason to use double quotes, for which the difficulty does not arise. It may even be a reason to use double quotes for quotations within quotations.  This is also the reason why you should use ''italics'' instead 'scare quotes' to mark words as words.
  
When punctuating quoted passages include the mark of punctuation inside the quotation marks ''only if'' the sense of the mark of punctuation is part of the quotation. This is the style used in Australia, New Zealand, and Britain, for example.  (A fuller treatment of the recommendations given here can be found in ''[[Fowler's Modern English Usage]]'' and other style guides for these countries, some of which vary in fine details.) "Stop!", for example, has the punctuation inside the quotation marks because the word "stop" is said with emphasis. When using "[[scare quotes]]", however, the comma goes outside.
+
When punctuating quoted passages include the mark of punctuation inside the quotation marks ''only if'' the sense of the mark of punctuation is part of the quotation. This is the style used in Australia, New Zealand, and Britain, for example.  (A fuller treatment of the recommendations given here can be found in ''Fowler's Modern English Usage'' and other style guides for these countries, some of which vary in fine details.) "Stop!," for example, has the punctuation inside the quotation marks because the word "stop" is said with emphasis. When using "scare quotes", however, the comma goes outside.
  
 
Other examples:
 
Other examples:
 
+
:Arthur said the situation was "deplorable". (''The full stop (period) is not part of the quotation.'')
:Arthur said the situation was "deplorable". (''The [[full stop]] (period) is not part of the quotation.'')
 
 
:Arthur said, "The situation is deplorable." (''The full sentence is quoted; the period is part of the quotation.'')
 
:Arthur said, "The situation is deplorable." (''The full sentence is quoted; the period is part of the quotation.'')
 
:Arthur said that the situation "was the most deplorable he had seen in years." (''Although the full sentence is not quoted, the sense of finality conveyed by the period is part of the quotation.'')
 
:Arthur said that the situation "was the most deplorable he had seen in years." (''Although the full sentence is not quoted, the sense of finality conveyed by the period is part of the quotation.'')
Line 116: Line 146:
  
 
====Look of quotation marks and apostrophes====
 
====Look of quotation marks and apostrophes====
 
 
There are two options when considering the look of the quotation marks themselves:
 
There are two options when considering the look of the quotation marks themselves:
  
* Typographic <big><b>“ ” ‘ ’</b></big>
+
*Typographic <big><b>“ ” ‘ ’</b></big>
* Typewriter <big><b>" '</b></big>
+
*Typewriter <big><b>" '</b></big>
  
 
As there is currently no consensus on which should be preferred, either is acceptable. However, it appears that historically the majority of Wikipedia articles, and those on the internet as a whole, follow the latter style.  If curved quotation marks or apostrophes appear in article titles, ensure that there is a redirect with straight glyphs.  
 
As there is currently no consensus on which should be preferred, either is acceptable. However, it appears that historically the majority of Wikipedia articles, and those on the internet as a whole, follow the latter style.  If curved quotation marks or apostrophes appear in article titles, ensure that there is a redirect with straight glyphs.  
  
 
Never use grave and acute accents or backticks (<big><b>` ´</b></big>) as quotation marks.
 
Never use grave and acute accents or backticks (<big><b>` ´</b></big>) as quotation marks.
 
===Use of punctuation in presence of brackets/parentheses===
 
Punctuation goes where it belongs logically; that is, it goes with the text to which it belongs. A sentence wholly inside brackets will have its punctuation inside the brackets. (As shown here, this applies to all punctuation in the sentence.) If a sentence ends with a clause in brackets, the final punctuation stays outside the brackets (as shown here). This applies to square "[ ]" as well as round "( )" brackets (parentheses).
 
 
===Serial commas===
 
The [[serial comma]] (also known as the '''Oxford comma''' or '''Harvard comma''') is a comma used immediately before a conjunction in a list of three or more items. The phrase "ham, chips, and eggs" is written with a serial comma, but "ham, chips and eggs" is not. Sometimes omitting the comma can lead to an ambiguous sentence, as in this example: "The author would like to thank her parents, Sinéad O'Connor and President Bush." In such cases, there are three options for avoiding ambiguity:
 
 
*A serial comma can be used to avoid ambiguity.
 
*The sentence can be recast to avoid listing the items in an ambiguous manner.
 
*The items in the list can be presented using a formatted list.
 
 
In most cases, however, the presence of the final serial comma does not affect ambiguity of the sentence, and in these cases there is no Wikipedia consensus on whether it should be used.
 
 
<!-- can someone double check Fowler? the rule here seems to be Brit = no comma, Amer = comma -->
 
Some style authorities support a mandatory final serial comma. These include Fowler's ''[[Fowler's Modern English Usage|Modern English Usage]]'' (Brit.), the ''[[Chicago Manual of Style]]'' (Amer.), and [[Strunk and White]]'s ''[[The Elements of Style|Elements of Style]]'' (Amer.). Other style authorities recommend avoiding the comma where possible. This holds true for the style guides used by ''[[The Times]]'' (Brit.) and ''[[The Economist]]'' (Brit.).
 
 
Proponents of the serial comma, such as ''The Elements of Style'', cite its disambiguating function and consistency as reasons for its use.  Opponents consider it extraneous in situations where it is not explicitly resolving ambiguity. Most non-journalistic style guides recommend its use while most newspaper style guides discourage its use; Wikipedia currently has no consensus.
 
 
By common convention, and by consensus of the Trains wikiproject, the serial comma should never be employed when specifying the name of a railroad or railway. For example, "[[Cleveland, Cincinnati, Chicago and St. Louis Railroad]]", not "[[Cleveland, Cincinnati, Chicago, and St. Louis Railroad]]".
 
  
 
===Colons===
 
===Colons===
 
[[Colon (punctuation)|Colons]] ( : ) should not have spaces before them, as in this example: "See? No space."
 
[[Colon (punctuation)|Colons]] ( : ) should not have spaces before them, as in this example: "See? No space."
 
 
 
===Spaces after the end of a sentence===
 
There are no guidelines on whether to use one or two spaces after the end of a sentence but it is not important as the difference shows up only in the edit box. See [[Wikipedia talk:Manual of Style archive (spaces after a full stop/period)|Wikipedia talk:Manual of Style archive (spaces after the end of a sentence)]] for a discussion on this.
 
  
 
===Contractions===
 
===Contractions===
In general, formal writing is preferred. Therefore, avoid excessive use of contractions&nbsp;&mdash; such as ''don't'', ''can't'', ''won't'', ''would've'', ''they'd'', and so on &mdash; unless they occur in a quotation.
+
In general, formal writing is preferred. Therefore, avoid excessive use of contractions&nbsp;&mdash; such as ''don't'', ''can't'', ''won't'', ''would've'', ''they'd'', and so on &mdash; unless they occur in a quotation or in a HOWTO article, written first-person.
  
 
==Acronyms and abbreviations==
 
==Acronyms and abbreviations==
Do not assume that your reader is familiar with the acronym or abbreviation that you are using.  The standard writing style is to spell out the acronym or abbreviation on the first reference (wikilinked if appropriate) and then show the acronym or abbreviation after it.  This signals to readers to look out for it later in the text, and makes it easy for them to refer back to it, for example:
+
Do not assume that your reader is familiar with the acronym or abbreviation that you are using.  The standard writing style is to spell out the acronym or abbreviation on the first reference (wiki-linked if appropriate) and then show the acronym or abbreviation after it.  This signals to readers to look out for it later in the text, and makes it easy for them to refer back to it, for example:
  
:The Brook Tree TV chip ([[bttv]]) is a commonly used chip amongst many vendors....
+
:The BrookTree TV chip ([[bttv]]) is a commonly used chip amongst many vendors....
  
 
It can also be helpful in a longer article to spell out the acronym or abbreviation for the reader again or to rewikify it if it has not been used for a while.
 
It can also be helpful in a longer article to spell out the acronym or abbreviation for the reader again or to rewikify it if it has not been used for a while.
 
 
 
 
 
 
  
 
==Simple tabulation==
 
==Simple tabulation==
Line 184: Line 183:
  
 
===Avoid self-referential pronouns===
 
===Avoid self-referential pronouns===
Wikipedia articles cannot be based on one person's opinions or experiences.  Thus, "I" can never be used, except, of course, when it appears in a quotation. For similar reasons, avoid the use of "we" and "one", as in: "We/One should note that some critics have argued in favor of the proposal", as it sounds more personal than encyclopedic.
+
Most MythTV wiki articles should not be based on one person's opinions or experiences -- except for HOWTOs.  Thus, "I" can never be used, except, of course, when it appears in a quotation. For similar reasons, avoid the use of "we" and "one", as in: "We/One should note that some critics have argued in favor of the proposal", as it sounds more personal than encyclopedic.
  
 
Nevertheless, it might sometimes be appropriate to use "we" or "one" when referring to an experience that ''anyone'', any reader, would be expected to have, such as general perceptual experiences. For example, although it might be best to write, "When most people open their eyes, they see something", it is still legitimate to write, "When we open our eyes, we see something", and it is certainly better than using the passive voice: "When the eyes are opened, something is seen".
 
Nevertheless, it might sometimes be appropriate to use "we" or "one" when referring to an experience that ''anyone'', any reader, would be expected to have, such as general perceptual experiences. For example, although it might be best to write, "When most people open their eyes, they see something", it is still legitimate to write, "When we open our eyes, we see something", and it is certainly better than using the passive voice: "When the eyes are opened, something is seen".
  
It is also acceptable to use "we" in mathematical derivations; for example: "To normalise the wavefunction we need to find the value of the arbitary constant ''A''..."
+
It is also acceptable to use "we" in mathematical derivations; for example: "To normalise the wavefunction we need to find the value of the arbitrary constant ''A''..."
 +
 
 +
This wiki does not require a style or view nearly as formal as Wikipedia, but authors should still strive, when possible, to present a certain feeling of professionalism and thoughtfulness in their writing -- especially writers for whom English is not a primary language.  All editors are invited to clean up weak syntax which obviously derives from this situation, while still trying to avoid taking "voice" out of first-person segments.
  
 
===Avoid the second person===
 
===Avoid the second person===
Line 196: Line 197:
 
*'''Not:''' "When ''you'' move past "go," ''you'' collect $200."
 
*'''Not:''' "When ''you'' move past "go," ''you'' collect $200."
 
This does not apply to quoted text, which should be quoted exactly.
 
This does not apply to quoted text, which should be quoted exactly.
 
 
  
 
==Pictures==
 
==Pictures==
 
 
Articles with a single picture are encouraged to have that picture at the top of the article, right-aligned, but this is not a hard and fast rule. Portraits with the head looking to the right should be left-aligned (looking into the article).  
 
Articles with a single picture are encouraged to have that picture at the top of the article, right-aligned, but this is not a hard and fast rule. Portraits with the head looking to the right should be left-aligned (looking into the article).  
  
 
The current image markup language is more or less this:
 
The current image markup language is more or less this:
  
  <code><nowiki>[[Image:picture.jpg|120px|right|thumb|Blah blah caption]]</nowiki></code>
+
  <code><nowiki>[[Image:picture.jpg|120px|right|thumb|Caption blah blah]]</nowiki></code>
  
 
==Captions==
 
==Captions==
{{main|Wikipedia:Captions}}
+
Photos and other graphics should have captions unless they are "self-captioning" as in reproductions of album or book covers, or when the graphic is an unambiguous depiction of the subject of the article. For example, in a biography article, a caption is not needed for a portrait of the subject, pictured alone, however most entries use the name of the subject and the birth and death years and an approximation of the date when the image was taken: "John Smith (1812-1895) circa 1880" or "John Smith (1812-1895) on January 12, 1880 in Paris". If the caption is a single sentence or a sentence fragment, it does not get a period at the end. If the caption contains more than one sentence, then each sentence should get a period at the end. The caption always starts with a capital letter. Remember the full information concerning the image is contained in the image entry, so people looking for more information can click on the photo to see the full details.
  
Photos and other graphics should have captions unless they are "self-captioning" as in reproductions of album or book covers, or when the graphic is an unambiguous depiction of the subject of the article. For example, in a biography article, a caption is not needed for a portrait of the subject, pictured alone, however most entries use the name of the subject and the birth and death years and an approximation of the date when the image was taken: "John Smith (1812-1895) circa 1880" or "John Smith (1812-1895) on January 12, 1880 in Paris". If the caption is a single sentence or a sentence fragment, it does not get a period at the end. If the caption contains more than one sentence, then each sentence should get a period at the end. The caption always starts with a capital letter. Remember the full information concerning the image is contained in the image entry, so people looking for more information can click on the photo to see the full details.
+
In particular, photo captions should not contain credits; the credit can be on the description page.
  
 
==Bulleted items==
 
==Bulleted items==
The following are rules for using lists of bulleted items:
+
These line item lists use the following guidelines:
* When using complete sentences always use punctuation and a period at the end.
+
*Complete sentences should use punctuation and an ending period.
* Incomplete sentence don't need terminal punctuation.
+
*Incomplete sentence do not need terminal punctuation.
* Dont mix sentence styles, use all complete sentences, or use all sentence fragments.
+
*Do not mix sentence styles &mdash; use all complete sentences, or use all sentence fragments.
* Each entry begins with a capital letter, even if it is a sentence fragments.
+
*Each entry begins with a capital letter, even if it is a sentence fragment.
  
==Identity==
+
==Wiki-linking==
This is perhaps one area where Wikipedians' flexibility and plurality are an asset, and where one would not wish all pages to look exactly alike. Wikipedia's [[Wikipedia:Neutral point of view|neutral point of view]] and [[Wikipedia:No original research|no original research]] policies always take precedence. However, here are some non-binding guidelines that may help:
+
Make only links relevant to the context. It is not useful and can be very distracting to mark all possible words as hyperlinks. Links should add to the user's experience; they should not detract from it by making the article harder to read. A high density of links can draw attention away from the high-value links that you would like your readers to follow up. Redundant links clutter up the page and make future maintenance harder. A link is the equivalent of a footnote in a print medium. Imagine if every second word in an encyclopedia article were followed by '(see:)'. Hence, the links should not be so numerous as to make the article harder to read.  
*Where known, use terminology that subjects use for themselves ([[self identification]]). This can mean calling an individual the term they use, or calling a group the term most widely used by that group. This includes referring to [[transgender]] individuals according to the name and pronoun they use to identify themselves.
 
*Use specific terminology: People from Ethiopia (a country in Africa) should be described as Ethiopian, not African.
 
*However, a more general name will often prove to be more neutral or more accurate. For example, a [[List of African-American composers]] is acceptable, though a [[List of composers of African descent]] may be more useful.
 
*If possible, terms used to describe people should be given in such a way that they [[grammatical modifier|qualify]] other nouns. Thus, ''black people'', not ''blacks''; ''gay people'', not ''gays''; and so forth.
 
*Do not assume that any one term is the most [[inclusive]] or [[accurate]].
 
*The term ''Arab'' refers to people and things of ethnic Arab origin. The term ''Arabic'' refers to the Arabic language or [[writing system]] (and related concepts). For example: ''Not all Arab people write or converse in Arabic, but nearly all are familiar with Arabic numerals.''
 
  
==Wiki-Linking==
+
Not every year listed in an article needs to be wiki-linked.  Ask yourself: will clicking on the year bring any useful information to the reader?
{{main|Wikipedia:Make only links relevant to the context}}
 
  
Make only [[Wikipedia:links|links]] relevant to the context. It is not useful and can be very distracting to mark all possible words as hyperlinks. Links should add to the user's experience; they should not detract from it by making the article harder to read. A high density of links can draw attention away from the high-value links that you would like your readers to follow up. Redundant links clutter up the page and make future maintenance harder. A link is the equivalent of a footnote in a print medium. Imagine if every second word in an encyclopedia article were followed by '(see:)'. Hence, the links should not be so numerous as to make the article harder to read.  
+
Do, however, wiki-link years, using the <nowiki>[[As of XXXX]]</nowiki> form, when they refer to information that was current at the time of writing; this allows other editors to ensure that articles are kept up to date as time passes. Dates including a month and day should also be linked, in order for user preferences on date formatting to work properly.
  
Not every year listed in an article needs to be wikilinked.  Ask yourself: will clicking on the year bring any useful information to the reader?
+
Check links after they are wikified to make sure they direct to the correct concept; many dictionary words lead to disambiguation pages and not to complete articles on a concept.
  
Do, however, wikilink years, using the <nowiki>[[As of XXXX]]</nowiki> form, when they refer to information that was current at the time of writing; this allows other editors to ensure that articles are kept up to date as time passesDates including a month and day should also be linked, in order for user preferences on date formatting to work properly. {{see also|Wikipedia:As of|Wikipedia:Manual of Style (dates and numbers)}}
+
Finally, do not be afraid to create links to pages you know do not exist yet; these can serve as hints to people as to what pages it would be useful to createIf you create such a page, though, be mindful that the phrasing someone used in creating a link might not be the best choice of article title; you may have to change the original writer's link into a [[piped link]] before clicking through it to create the article.
  
Check links after they are wikified to make sure they direct to the correct concept; many dictionary words lead to disambiguation pages and not to complete articles on a concept.
+
== External linking ==
 +
Wikipedia, as a policy, prefers author/editors to group external links at the bottom of an article, in a named section. The MythTV wiki, as policy, does not care. If you want to use an external link in-line under a descriptive piece of a sentence, knock yourself out.
  
 
==Miscellaneous notes==
 
==Miscellaneous notes==
 
===When all else fails===
 
===When all else fails===
If this page does not specify which usage is preferred, use other resources, such as ''[[The Chicago Manual of Style]]'' (from the [[University of Chicago Press]]) or [[Fowler's Modern English Usage|Fowler's ''Modern English Usage'' (3rd edition)]] (from the [[Oxford University Press]]). Also, please feel free to carry on a discussion on [[Wikipedia talk:Manual of Style]], especially for substantive changes.
+
If this page does not specify which usage is preferred, use other resources, such as ''The Chicago Manual of Style'' (from the University of Chicago Press) or Fowler's ''Modern English Usage'' (3rd edition) (from the Oxford University Press). Also, please feel free to carry on a discussion on [[MythTV talk:Manual of Style|the style guide's talk page]], especially for substantive changes.
  
 
Even simpler is to look at an article that you like and open it for editing to see how the writers and editors have put it together. You can then close the window without saving changes if you like, but look around while you are there. Almost every article can be improved.
 
Even simpler is to look at an article that you like and open it for editing to see how the writers and editors have put it together. You can then close the window without saving changes if you like, but look around while you are there. Almost every article can be improved.
Line 251: Line 243:
  
 
===Formatting issues===
 
===Formatting issues===
Formatting issues such as font size, blank space and color are issues for the Wikipedia site-wide [[Cascading Style Sheets|style sheet]] and should not be dealt with in articles except in special cases. If you absolutely must specify a font size, use a relative size i.e. <code>font-size: 80%</code>; not an absolute size, for example, <code>font-size: 4pt</code>. Color coding of information should not be done, but if necessary, try to choose colors that are unambiguous when viewed by a person with [[color blindness]]. In general, this means that red and green should not both be used. Viewing the page with Vischeck ([http://www.vischeck.com/vischeck/vischeckURL.php http://www.vischeck.com/vischeck/vischeckURL.php]) can help with deciding if the colors should be altered.
+
Formatting issues such as font size, blank space and color are issues for the Wikipedia site-wide style sheet and should not be dealt with in articles except in special cases. If you absolutely must specify a font size, use a relative size i.e. <code>font-size: 80%</code>; not an absolute size, for example, <code>font-size: 4pt</code>. Color coding of information should not be done, but if necessary, try to choose colors that are unambiguous when viewed by a person with color blindness. In general, this means that red and green should not both be used. Viewing the page with Vischeck ([http://www.vischeck.com/vischeck/vischeckURL.php http://www.vischeck.com/vischeck/vischeckURL.php]) can help with deciding if the colors should be altered.
  
 
===Make comments invisible===
 
===Make comments invisible===
Line 271: Line 263:
  
 
===Legibility===
 
===Legibility===
Consider the [[legibility]] of what you are writing. Make your entry easy to read on a screen. Make judicious use of devices such as bulleted lists and bolding. More on this has been written by [[Jakob Nielsen (usability consultant)|Jakob Nielsen]] in [http://www.useit.com/alertbox/9710a.html How Users Read on the Web].
+
Consider the legibility of what you are writing. Make your entry easy to read on a screen. Make judicious use of devices such as bulleted lists and bolding. More on this has been written by Jakob Nielsen in [http://www.useit.com/alertbox/9710a.html How Users Read on the Web].
 
 
==See also==
 
<!-- This list is now sorted alphabetically. You are free to edit it further if you have an idea how to sort them better. Please, when adding a link, also provide a short resume of the article. --[[User:Eleassar777|Eleassar777]] 06:32, 19 Apr 2005 (UTC) -->
 
*[[Style guide]], the Wikipedia entry on "style guides". Contains links to the online style guides of some magazines and newspapers.
 
*[[Wikipedia:Annotated article]] - the article contains annotations that show how it should be edited preferentially.
 
*[[Wikipedia:Avoiding common mistakes]] gives a list of common mistakes and how to avoid them.
 
*[[Wikipedia:Be bold in updating pages]] should define your attitude toward page updates.
 
*[[Wikipedia:Cite sources]] explains process and standards for citing references in articles.
 
*[[Wikipedia:Editing policy]] has even more editing guidelines.
 
*[[Wikipedia:Guide to layout]] is an example of how to lay out an article.
 
*[[Wikipedia:How to edit a page]] is a short primer on editing pages.
 
*[[Wikipedia:Introduction]] is a gentle introduction to the world of Wikipedia.
 
*[[Wikipedia:Perfect stub article]] shows what you should aim for at a minimum when starting a new article.
 
*[[Wikipedia:Policies and guidelines]] is the main stop for policies and, well, guidelines.
 
*[[Wikipedia:How to edit a page#Wiki markup|Wiki markup]] explains the mechanics of what codes are available to you when editing a page, to do things like titles, links, external links, and so on.
 
*[[Wikipedia:WikiProject]] sets out boilerplates for certain areas of knowledge.
 
*[[Meta:Reading level]] (discussion)
 
  
[[Category:MythTV style guidelines]]
+
[[Category:Knowledge Base]]

Latest revision as of 12:48, 14 November 2006

Blue check.png This page is a style guide for MythTV. The consensus of many editors formed the conventions described here. MythTV articles should heed these rules. Feel free to update this page as needed, but please use the discussion page to propose major changes.


This Manual of Style has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules do not claim to be the last word on MythTV wiki-style. One way is often as good as another, but if everyone does it the same way, the MythTV wiki will be easier to read and use, not to mention easier to write and edit. In this regard, the following quotation from The Chicago Manual of Style deserves notice:

Rules and regulations such as these, in the nature of the case, cannot be endowed with the fixity of rock-ribbed law. They are meant for the average case, and must be applied with a certain degree of elasticity.

Clear, informative, and unbiased writing is always more important than presentation and formatting. Writers are not required to follow all or any of these rules: the joy of wiki editing is that perfection is not required.

Note that this Style Manual was stolen bodily from Wikipedia; there will certainly be things we'll need to change, as we have differering requirements than they do. Above all, remember The Wiki Way: try not to be offended if someone (particularly someone like Isaac, Tyler, Dan, Kevin, David, Steve, Greg, or myself) makes a change to a style or policy item you've contributed to. Wiki's are all about everyone contributing, but someone does occasionally have to herd the cats.  :-)


Article titles

If possible, make the title the subject of the first sentence of the article (as opposed to putting it in the predicate). For example, write "This Manual of Style is a style guide" instead of "This style guide is known as the Manual of Style." In any case, the title should appear as early as possible in the article — preferably in the first sentence.

The first time the title is mentioned in the article, put it in bold using three apostrophes — '''article title''' produces article title. For example: "This Manual of Style is a style guide."

As a general rule, do not put links in

  1. the bold reiteration of the title in the article's lead sentence or
  2. any section title.

Also, try not to put other phrases in bold in the first sentence.

Follow the normal rules for italics in choosing whether to put part or all of the title in italics.

Singular vs. Plural

It is better to name an article in the singular instead of plural notation, because it is easier to add plurality later in a sentence instead of removing it with a pipe.

[[Video Capture Card]]s
is easier to maintain than
[[Video Capture Cards|Video Capture Card]]

Upper case/lower case/mixed case

Mediawiki automatically "uppers" article names. Every letter after the first, however, is case sensitive. To make your articles easier to link inline to those of others, use lowercase for the rest of the article unless it is a proper noun.

What you type:

What it looks like What you type
For example, it is easier to link to a sentence about scheduling recordings than to link to one about scheduling recordings.
For example, it is easier to link to a
sentence about [[scheduling recording]]s
than to link to one about
[[Scheduling Recordings|scheduling recordings]].

P.S. The singular rule would also be good in this case.

Headings

Use the == (two equal signs) style markup for headings, not the ''' (triple apostrophes) used to make words appear bold in character formatting. Start with "==", add the heading title, then end with "==".

Capitalize only the first letter of the first word or the first letter of any proper nouns in a heading, and leave all other letters in lowercase.

Also note the following:

  • Avoid links within headings.
  • Avoid overuse of sub-headings.
  • Avoid "The" in headings. For example, use "Voyage" instead of "The voyage".
  • Avoid repeating the article title in the heading. For example, use "Voyage" instead of "Voyage of the Mayflower" in an article titled "Mayflower".
  • In general, avoid level 1 headings '='; they tend to stand out too much in the flow of a page. Tables of contents will be numbered based on the lowest numerical level heading, so they will not look silly.

Capital letters

Titles

Titles such as president, king, or emperor start with a capital letter when used as a title (followed by a name): "President Nixon", not "president Nixon". When used generically, they should be in lower case: "De Gaulle was the French president." The correct formal name of an office is treated as a proper noun. Hence: "Hirohito was Emperor of Japan". Similarly "Louis XVI was the French king" but "Louis XVI was King of France", King of France being a title in that context. Likewise, royal titles should be capitalized: "Her Majesty" or "His Highness". (Reference: Chicago Manual of Style 14th ed., par. 7.16; The Guardian Manual of Style, "Titles" keyword.) Exceptions may apply for specific offices.

In the case of "prime minister", either both words begin with a capital letter or neither, except, obviously, when it starts a sentence. Again, when being used generically, no capital letter is used: "There are many prime ministers around the world." When reference is made to a specific office, upper case is generally used: "The British Prime Minister, Tony Blair, said today..." (A good rule of thumb is whether a definite article (the) or an indefinite article (a) is used. If the is used, use "Prime Minister". If a is used, go with "prime minister". However to complicate matters, some style manuals, while saying "The British Prime Minister", recommend "British prime minister".)

American English and Commonwealth English differ in their inclination to use capitals. Commonwealth English uses capitals more widely than American English does. This may apply to titles for people. If possible, as with spelling, use rules appropriate to the cultural and linguistic context. In other words, do not enforce American rules on pages about Commonwealth topics or Commonwealth rules on pages about American topics. In regard to pages about other cultures, choose either style, but be consistent within the page itself.

Calendar items

The names of months, days, and holidays always begin with a capital letter: June, Monday, Fourth of July.

Seasons start with a capital letter when they are used with another noun or are personified. Here they function as proper nouns: "Winter Solstice"; "Autumn Open House"; "I think Spring is showing her colors"; "Old Man Winter".

However, they do not start with a capital letter when they are used generally: "This summer was very hot."

As Of dates and versions

If you're talking about a feature that now exists "as of" a specific version, please put as of 0.19 (or whatever version it may be, and wiki-link it. This will permit us to go to that page, and check What Links Here, to find out what things need to be updated as new versions are released. This is not necessary in the User Manual; it's expected that that section will be maintained as up-to-date as possible as new releases come out.

Italics

Use the '' (italic) markup. Example:

''This is italic.''

which produces:

This is italic.

Italics are mainly used to emphasize certain words. They are also used in other cases that are mentioned here.

Titles

Italics should be used for titles of the following:

  • Books
  • Computer and video games
  • Films
  • Foreign language words
  • Musical albums
  • Orchestral works
  • Periodicals (newspapers, journals, and magazines)
  • Television series
  • Works of visual art

Italics are generally used for titles of longer works. Titles of shorter works, such as the following, should be enclosed in double quotation marks:

  • Articles, essays or papers
  • Chapters of a longer work
  • Episodes of a television series
  • Short poems
  • Short stories
  • Songs

Words as words

Use italics when writing about words as words, or letters as letters (to indicate the use-mention distinction). For example:

  • Deuce means two.
  • The term panning is derived from panorama, a word originally coined in 1787.
  • The most common letter in English is e.

Quotations

There is normally no need to put quotations in italics unless the material would otherwise call for italics (emphasis, use of non-English words, etc.). It is necessary to indicate whether the italics are used in the original text or were added later. For example:

Now cracks a noble heart. Good night sweet prince: And flights of angels sing thee to thy rest!

(emphasis added).

You can do the indentation either using HTML's <blockquote> tag, or by indenting the paragraph on a ":".

Punctuation

In most cases, simply follow the usual rules of English punctuation. A few points where MythTV may differ from usual usage follow.

Quotation marks

With quotation marks, we split the difference between American and British usage. Though not a rigid rule, we use the "double quotes" for most quotations—they are easier to read on the screen—and use 'single quotes' for nesting quotations, that is, "quotations 'within' quotations".

Note: if a word or phrase appears in an article with single quotes, such as 'abcd', the Searching facility considers the single quotes to be part of the word and will find that word or phrase only if the search string is also within single quotes. (When trying this out with the example mentioned, remember that this article is in the Wikipedia namespace.) Avoiding this complication is an additional reason to use double quotes, for which the difficulty does not arise. It may even be a reason to use double quotes for quotations within quotations. This is also the reason why you should use italics instead 'scare quotes' to mark words as words.

When punctuating quoted passages include the mark of punctuation inside the quotation marks only if the sense of the mark of punctuation is part of the quotation. This is the style used in Australia, New Zealand, and Britain, for example. (A fuller treatment of the recommendations given here can be found in Fowler's Modern English Usage and other style guides for these countries, some of which vary in fine details.) "Stop!," for example, has the punctuation inside the quotation marks because the word "stop" is said with emphasis. When using "scare quotes", however, the comma goes outside.

Other examples:

Arthur said the situation was "deplorable". (The full stop (period) is not part of the quotation.)
Arthur said, "The situation is deplorable." (The full sentence is quoted; the period is part of the quotation.)
Arthur said that the situation "was the most deplorable he had seen in years." (Although the full sentence is not quoted, the sense of finality conveyed by the period is part of the quotation.)

Longer quotations may be better rendered in an indented style by starting the first line with a colon or by using <blockquote> </blockquote> notation, which indents both left and right margins. Indented quotations do not need to be marked by quotation marks. Double quotation marks belong at the beginning of each paragraph in a quotation of multiple paragraphs not using indented style, though at the end of only the last paragraph.

Use quotation marks or indentations to distinguish quotations from other text. There is normally no need to put quotations in italics unless the material would otherwise call for italics (emphasis, use of non-English words, etc.).

Look of quotation marks and apostrophes

There are two options when considering the look of the quotation marks themselves:

  • Typographic “ ” ‘ ’
  • Typewriter " '

As there is currently no consensus on which should be preferred, either is acceptable. However, it appears that historically the majority of Wikipedia articles, and those on the internet as a whole, follow the latter style. If curved quotation marks or apostrophes appear in article titles, ensure that there is a redirect with straight glyphs.

Never use grave and acute accents or backticks (` ´) as quotation marks.

Colons

Colons ( : ) should not have spaces before them, as in this example: "See? No space."

Contractions

In general, formal writing is preferred. Therefore, avoid excessive use of contractions — such as don't, can't, won't, would've, they'd, and so on — unless they occur in a quotation or in a HOWTO article, written first-person.

Acronyms and abbreviations

Do not assume that your reader is familiar with the acronym or abbreviation that you are using. The standard writing style is to spell out the acronym or abbreviation on the first reference (wiki-linked if appropriate) and then show the acronym or abbreviation after it. This signals to readers to look out for it later in the text, and makes it easy for them to refer back to it, for example:

The BrookTree TV chip (bttv) is a commonly used chip amongst many vendors....

It can also be helpful in a longer article to spell out the acronym or abbreviation for the reader again or to rewikify it if it has not been used for a while.

Simple tabulation

Any line that starts with a blank space becomes a fixed font width and can be used for simple tabulation.

foo     bar     baz
alpha   beta  gamma

A line that starts with a blank space with nothing else on it forms a blank line.

Usage and spelling

Usage

  • Possessives of singular nouns ending in s may be formed with or without an additional s. Either form is generally acceptable within Wikipedia. However, if either form is much more common for a particular word or phrase, follow that form, such as with "Achilles' heel".
  • Abbreviations of Latin terms like "i.e.", "e.g.", or "n.b." should be avoided and English terms such as "that is", "for example", or "note" used instead.
  • If a word or phrase is generally regarded as correct, then prefer it to any other word or phrase that might be regarded as incorrect. For example, "other meaning" should be used instead of "alternate meaning" or "alternative meaning", because not all English speakers regard "alternate" and "alternative" as meaning the same. The American Heritage Dictionary "Usage Note" at alternative says: "Alternative should not be confused with alternate." Alternative commonly suggests "non-traditional" or "out-of-the-mainstream" to an American-English speaker. Some traditional usage experts consider alternative to be appropriate only when there are exactly two alternatives.

Avoid self-referential pronouns

Most MythTV wiki articles should not be based on one person's opinions or experiences -- except for HOWTOs. Thus, "I" can never be used, except, of course, when it appears in a quotation. For similar reasons, avoid the use of "we" and "one", as in: "We/One should note that some critics have argued in favor of the proposal", as it sounds more personal than encyclopedic.

Nevertheless, it might sometimes be appropriate to use "we" or "one" when referring to an experience that anyone, any reader, would be expected to have, such as general perceptual experiences. For example, although it might be best to write, "When most people open their eyes, they see something", it is still legitimate to write, "When we open our eyes, we see something", and it is certainly better than using the passive voice: "When the eyes are opened, something is seen".

It is also acceptable to use "we" in mathematical derivations; for example: "To normalise the wavefunction we need to find the value of the arbitrary constant A..."

This wiki does not require a style or view nearly as formal as Wikipedia, but authors should still strive, when possible, to present a certain feeling of professionalism and thoughtfulness in their writing -- especially writers for whom English is not a primary language. All editors are invited to clean up weak syntax which obviously derives from this situation, while still trying to avoid taking "voice" out of first-person segments.

Avoid the second person

Use of the second person ("you") is generally discouraged. This is to keep an encyclopedic tone, and also to help clarify the sentence. Instead, refer to the subject of the sentence, for example:

  • "When a player moves past "go," that player collects $200."
    • Or, even better: "Players passing 'go' collect $200."
  • Not: "When you move past "go," you collect $200."

This does not apply to quoted text, which should be quoted exactly.

Pictures

Articles with a single picture are encouraged to have that picture at the top of the article, right-aligned, but this is not a hard and fast rule. Portraits with the head looking to the right should be left-aligned (looking into the article).

The current image markup language is more or less this:

[[Image:picture.jpg|120px|right|thumb|Caption blah blah]]

Captions

Photos and other graphics should have captions unless they are "self-captioning" as in reproductions of album or book covers, or when the graphic is an unambiguous depiction of the subject of the article. For example, in a biography article, a caption is not needed for a portrait of the subject, pictured alone, however most entries use the name of the subject and the birth and death years and an approximation of the date when the image was taken: "John Smith (1812-1895) circa 1880" or "John Smith (1812-1895) on January 12, 1880 in Paris". If the caption is a single sentence or a sentence fragment, it does not get a period at the end. If the caption contains more than one sentence, then each sentence should get a period at the end. The caption always starts with a capital letter. Remember the full information concerning the image is contained in the image entry, so people looking for more information can click on the photo to see the full details.

In particular, photo captions should not contain credits; the credit can be on the description page.

Bulleted items

These line item lists use the following guidelines:

  • Complete sentences should use punctuation and an ending period.
  • Incomplete sentence do not need terminal punctuation.
  • Do not mix sentence styles — use all complete sentences, or use all sentence fragments.
  • Each entry begins with a capital letter, even if it is a sentence fragment.

Wiki-linking

Make only links relevant to the context. It is not useful and can be very distracting to mark all possible words as hyperlinks. Links should add to the user's experience; they should not detract from it by making the article harder to read. A high density of links can draw attention away from the high-value links that you would like your readers to follow up. Redundant links clutter up the page and make future maintenance harder. A link is the equivalent of a footnote in a print medium. Imagine if every second word in an encyclopedia article were followed by '(see:)'. Hence, the links should not be so numerous as to make the article harder to read.

Not every year listed in an article needs to be wiki-linked. Ask yourself: will clicking on the year bring any useful information to the reader?

Do, however, wiki-link years, using the [[As of XXXX]] form, when they refer to information that was current at the time of writing; this allows other editors to ensure that articles are kept up to date as time passes. Dates including a month and day should also be linked, in order for user preferences on date formatting to work properly.

Check links after they are wikified to make sure they direct to the correct concept; many dictionary words lead to disambiguation pages and not to complete articles on a concept.

Finally, do not be afraid to create links to pages you know do not exist yet; these can serve as hints to people as to what pages it would be useful to create. If you create such a page, though, be mindful that the phrasing someone used in creating a link might not be the best choice of article title; you may have to change the original writer's link into a piped link before clicking through it to create the article.

External linking

Wikipedia, as a policy, prefers author/editors to group external links at the bottom of an article, in a named section. The MythTV wiki, as policy, does not care. If you want to use an external link in-line under a descriptive piece of a sentence, knock yourself out.

Miscellaneous notes

When all else fails

If this page does not specify which usage is preferred, use other resources, such as The Chicago Manual of Style (from the University of Chicago Press) or Fowler's Modern English Usage (3rd edition) (from the Oxford University Press). Also, please feel free to carry on a discussion on the style guide's talk page, especially for substantive changes.

Even simpler is to look at an article that you like and open it for editing to see how the writers and editors have put it together. You can then close the window without saving changes if you like, but look around while you are there. Almost every article can be improved.

Keep markup simple

Use the simplest markup to display information in a useful and comprehensible way. Markup may appear differently in different browsers. Use HTML and CSS markup sparingly and only with good reason. Minimizing markup in entries allows easier editing.

In particular, do not use the CSS float or line-height properties because they break rendering on some browsers when large fonts are used.

Formatting issues

Formatting issues such as font size, blank space and color are issues for the Wikipedia site-wide style sheet and should not be dealt with in articles except in special cases. If you absolutely must specify a font size, use a relative size i.e. font-size: 80%; not an absolute size, for example, font-size: 4pt. Color coding of information should not be done, but if necessary, try to choose colors that are unambiguous when viewed by a person with color blindness. In general, this means that red and green should not both be used. Viewing the page with Vischeck (http://www.vischeck.com/vischeck/vischeckURL.php) can help with deciding if the colors should be altered.

Make comments invisible

Avoid highlighting that the article is incomplete and in need of further work.

Similarly, there is little benefit to the reader in seeing headings and tables without content.

If you want to communicate with other potential editors, make comments invisible to the ordinary article reader. To do so, enclose the text which you intend to be read only by editors within <!-- and -->.

For example, the following:

hello <!-- This is a comment. --> world

is displayed as:

hello world

So the comment can be seen when viewing the HTML or wiki source.

Legibility

Consider the legibility of what you are writing. Make your entry easy to read on a screen. Make judicious use of devices such as bulleted lists and bolding. More on this has been written by Jakob Nielsen in How Users Read on the Web.