From CpapWiki
Revision as of 14:06, 16 October 2008 by Sleeppunk (talk | contribs)
Jump to: navigation, search

CpapWiki:Manual of Style

The Manual of Style (MoS) is intended to bring some general guidelines to the way articles and pages should be formatted and structured to help make the CPAPtalk.com CPAP Wiki better. One of the nice things about a wiki is that edits do not have to be perfect since they may always be changed for correction or improvement later on. These guidelines are not "law", but will serve to make the site more uniform, and therefore easier to use. Editors should try to follow these guidelines but there are always exceptions to every rule. Above all, use common sense.

Article titles

In choosing a title for a new page or article, use the following guidelines.

  • Use English.
  • Use the singular.
  • Avoid special characters.
  • Avoid using a, an, or the as the first word.
  • Avoid abbreviations.

If the wrong name is chosen for a title, the page can be moved by a Sysop, which will automatically create a redirect from the old title to the new title. Redirects should also be made from all other entries someone might type when looking for your article.

First sentence

The article should begin with a straightforward, declarative first sentence that will help the reader understand what the article contains.

As a general rule, the first (and only the first) appearance of the page title should be in the first sentence, as soon as possible, and should be bolded. Use as few links as possible before and in the bolded title.

If the subject of the page has a common abbreviation or more than one name, the abbreviation (in parenthesis) and each additional name should be bolded on its first appearance.

Sections and headers

Headings provide a table of contents and allow for quick navigation of the article. Here are some guidelines for section titles and headers.

  • Try not to change section headings (and sub-headings) too often, because other articles may have linked to a section and changing it would break those links. If you do change a section name, try to find what links to that section and fix the broken links.
  • Section names should be unique within a page. This also applies to subsections. Duplication of section names may result in a user arriving at the wrong point on the page after an edit, and may cause difficulty in understanding the page history, or linking to the proper section.
  • Links should not be used in headings. Instead link the first appearance of the word in a sentence.
  • Capitalize the first letter of the first word only. Exceptions are proper nouns (names given to individual people, places, companies, or brands), which should be capitalized in a section name, or header.
  • Section titles should not be bolded.
  • Do not italicize the section name, unless it needs italics (for example: a book title).
  • Do not use special characters in headings.
  • Try to keep the section title short with preferably 10 words, or less.
  • Do not use the title of the whole article as a heading.
  • A blank line below the heading is optional. If there are no blank lines above the heading, one line should be added, for readability in the edit window. Only two or more blank lines above or below will change the public appearance of the page by adding more white space.

Capitalization

Capital letters should not be used for emphasis. Use italics instead.

Incorrect:    Capital letters should Not be used for emphasis. Use italics instead.
Incorrect: Capital letters should NOT be used for emphasis. Use italics instead.
Correct: Capital letters should not be used for emphasis. Use italics instead.
  • Months, days of the week, and holidays should start with a capital letter.
  • Seasons, in almost all instances, are lowercase. When personified, season names may function as proper nouns, and they should then be capitalized.

Italics

  • Use italics sparingly for emphasis.
  • Use italics for title of books, literature, and works of art. Titles of articles, chapters, and other short works should not be italicized, but instead should be in quotation marks.
  • Use italics for words or phrases in other languages.
  • Use italics when writing about words as words, or letters as letters.
    • Example: The word apnea comes from the Greek word ἄπνοια.
  • Do not substitute italics for quotation marks when quoting. Use quotation marks instead.
  • Do not italicize a quotation just because it is a quotation.
  • Try not to italicize punctuation.

Acronyms and abbreviations

Do not assume that readers will know the meaning of acronyms and abbreviations used in an article. At the first occurrence, use the full version of the acronym or abbreviation followed by the abbreviation in parentheses.

  • For example: A Manual of Style (MoS) consists of general guidelines for writing on the wiki.

Do not use unnecessary abbreviations. In other words, do not write an article and use approx. every time the word approximately should be used.

Do not invent abbreviations and acronyms.

Acronyms and abbreviations are made plural by adding -s or -es.

  • For example: DMEs across the country are selling CPAP masks.

Modern style books do not use as many periods and spaces with acronyms and abbreviations for personal titles, as were used in the past. For example, PhD is more common than Ph.D. or Ph. D., and is preferred here. If an abbreviation is not clear without periods, the periods should not be removed.

Punctuation

Quotation marks

The guideline here is that quotations are enclosed within "double quotes". Quote marks within quotations are enclosed within 'single quotes'.

Punctuation marks are placed inside the quotation marks only if the sense of the punctuation is a part of the quotation.

  • Examples: (Examples needed)
    • Example 1:
    • Example 2:
    • Example 3:
    • Example 4:

Try not to link words that are in quotes.

Do not italicize words within quotations, unless the original quote is italicized.

The author of a quote of a full sentence or more should be named in the main text and not in a footnote.

Block Quotes

For longer quotes of four lines or more, block quotes should be used. The quotations must be precise and exactly as in the source. The source should be cited clearly and precisely to enable readers to find the text that supports the article content in question. Block quotes can be enclosed between a pair of <blockquote>...</blockquote> HTML tags.

Note: The current version of the MediaWiki software does not render multiple paragraphs inside a <blockquote> when spacing the paragraphs apart with a blank line. Instead, enclose each of the block-quoted paragraphs in its own <p>...</p> HTML tags.

Example:

<blockquote>
<p>Please Note: Return insurance is available to all customers, however, return labels are only offered within the 48 contiguous United States. If return insurance is purchased by a customer living outside the 48 contiguous United States, all shipping costs involved are paid by the customer and the mask must be received back within the 30 day insurance time frame.</p>

<p>—CPAP.com, ''Return Insurance''</p>
</blockquote>

The result appears indented on both sides:

Please Note: Return insurance is available to all customers, however, return labels are only offered within the 48 contiguous United States. If return insurance is purchased by a customer living outside the 48 contiguous United States, all shipping costs involved are paid by the customer and the mask must be received back within the 30 day insurance time frame.

—CPAP.com, Return Insurance

Types of quotation marks

Two options may be considered regarding the look of the quotation marks themselves:

  • Typewriter or straight: example, example
  • Typographic or curly: "example", 'example'

Either example above is okay.

  • Please note: Never use grave and acute accents or backticks (`text´) as quotation marks or apostrophes.

Brackets and parentheses

Punctuation in a sentence should go outside of the brackets, (if the bracketed phrase is only part of a sentence). [If the whole sentence is inside of the brackets, then the punctuation goes on the inside.]

  • Do not place spaces next to the inside of brackets or parentheses.
  • Usually, place a space before and after brackets or parentheses, unless there is punctuation that belongs right after a bracket or parentheses.
  • Try to avoid placing two sets of brackets or parentheses next to each other.
  • Try to avoid nesting brackets and parentheses. If nesting them is necessary though, use the contrasting type (square brackets within round brackets [like this]). It would usually be better to revise the sentence using commas, semicolons, colons or dashes instead.

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 "bacon, lettuce, and tomato" is written with a serial comma, but "bacon, lettuce and tomato" is not.

Sometimes not using a serial comma makes a sentence unclear, as in this example:
The author would like to thank his grandfathers, David Brown and Erwin Mooney, which may be a list of either four people (the two grandfathers and the two people named) or two people (Brown and Mooney, who are the grandfathers).

There are times where using the comma can also make a sentence unclear, as in:
The author would like to thank his grandfather, David Brown, and Erwin Mooney, which may be a list of either two people (Brown, who is the grandfather, and Mooney) or three people (the first being the grandfather, the second being Brown, and the third being Mooney).

In such cases, there are three options to clarify the sentence:

  • Leave or omit the comma to avoid ambiguity.
  • Rewrite the sentence in a way that is more clear.
  • The items in the list can be presented using a formatted list.

Colons

Generally, a colon (:) instructs the reader that what follows it proves and explains, or simply elaborates elements of what is referred to previously.

Colons should not have any spaces before them:

Correct: Example: This is the example.
Incorrect:    Example : This is the example.

Hyphens and dashes

The hyphen (-) is used to form compound words, such as well-known. The en dash (–) is used to specify numeric ranges, such as open 9–5. The em dash (—) can be used to link clauses of a sentence—like this one—as can the spaced en dash ( – ). Other dashes, such as the double-hyphen (--), should not be used.

Slashes

Please do not to join two words together with a slash (/), because it implies that they are related, but does not clearly state how. Usually there are better choices than a slash. If at all possible, be more specific and re-word things more fully to avoid use of a slash between two words.

An example: "The CPAP/BiPAP should be used when sleeping." Should both be used? (Then write and say "the CPAP and the BiPAP".) Should at least one be present? (Then write and say "the CPAP or the BiPAP".)

In situations involving a distinction or disjunction, the en dash (–) is usually better than the slash. For example: "the cigar–cigarillo distinction".

The slash does have some good uses. It can be used to separate lines of poetry, or to show how something is spoken or pronounced ("CPAP is pronounced /see-pap/"), or to separate the numbers in a fraction ("1/2")

And/or

Use of and/or should be avoided because it may cause ambiguity or confusion for the reader. For example, "a and/or b" can be written as "a or b, or both", or "either a or b" and optionally add to the end "but not both", if needed to clarify.

When there are more than two choices, it is even more important to not use and/or. With two choices, at least the intention is relatively clear. But, when more than two choices are used it may be difficult to know what is trying to be conveyed. Instead of "a, b, and/or c", try using an appropriate alternative: "one or more of a, b, and c" or, "some or all of a, b, and c".

Spaces after the end of a sentence

There are no guidelines on whether to use one space or two spaces after the end of a sentence. The issue is not important here because the difference is visible only in the edit boxes and is ignored by browsers when displaying the article or wiki pages.

Ellipses

An ellipsis is a series of 3 (sometimes 4) periods or dots (...), that is used to represent words that have been left out. Often they are used for partial quotes, or in representing printed conversation. Sometimes, it is used at the end of a sentence, in which case 4 dots are normally used.

  • Try not to use ellipses here except for using them in partial quotations.
  • Do not place spaces between the dots.
  • Use non-breaking spaces (&nbsp;) only as needed to prevent improper line breaks, e.g.:
    • To keep a quotation mark from being separated from the start of the quotation: "...&nbsp;this is truly amazing."
    • To keep the ellipsis from wrapping to the next line: "CPAP machines, masks,&nbsp;... and supplies but not wheelchairs."

Question marks and exclamation points

Here are some general guidelines to follow:

  • A question mark (?) or exclamation mark (!) should never be preceded by a space.
  • Exclamation marks should be used sparingly and with great restraint.
  • Do not use multiple question or exclamation marks in an article (???, !!!). It is not appropriate here.

Ampersand

The ampersand (&) is a symbol representing the word and. In writing articles, and should primarily be used instead because it is more formal. Exception: If it appears in the titles of businesses, works, or in a quote, the use of an ampersand is acceptable. The ampersand may also be used in tables, infoboxes, and other places where the writer has limited space constraints.

Date and time

Be precise

It is important to be careful about the use of statements that refer to time, and that may become out of date quickly. Statements like currently, soon, recently, is now considered, and in the near future, are some examples of these type of statements. They should be avoided in most cases.

Instead use more precise statements like these:

  • as of January 12th, 2008; since October 2006; in June of 1999; during the 1970s; etc.

Time formats

  • Use either the 12 or 24 hour clock.
  • Both use a colon to separate hours, minutes, and seconds (5:52:03 pm and 17:52:03).
  • 12 hour formats should end with dotted or undotted lower-case a.m. or p.m., or am or pm. Place a non-breaking space between the time and the a.m. or p.m. ("5:52 p.m." or "5:52 pm", not "5:52p.m." or "5:52pm").
    • To create a non-breaking space, type "&nbsp;", like so: "5:52&nbsp;p.m." Use noon or 12 noon and midnight or 12 midnight, instead of 12 pm and 12 am.
  • 24 hour formats do not use a.m. or p.m., or am or pm. Also, use 00:00 for midnight at the start of a date, 12:00 for noon, and 24:00 for midnight at the end of a date.

Date formats

The general rule of thumb is to be consistent within an article with date formats. If one format is already used in an article, stick with that format, unless there is some good reason to change it.

  • Use either the U.S. format (May 31 and May 31, 1999) or the International format (31 May and 31 May 1999).
  • The U.S. format should have a comma between day and year. There are no commas in the International format.
  • Do not use ordinal suffixes such as 1st, 2nd, 3rd, 4th.
  • Do not place a comma between the month and day.
  • Do not place a comma in between month and year if the date is month and year only.

Longer periods of time

Here are some guidelines for longer time periods.

  • Months should not be abbreviated or expressed as numerals, except in rare cases when space is an issue such as in infoboxes or tables. Also, do not place the word of between a month and year.
  • Seasons used in dates should be avoided, if possible. Because of the international nature of the internet, and varying seasons depending on the hemisphere where a person resides, using something like Summer 2001 could be ambiguous. It is preferred that a month and date be used instead.
  • Years should not have commas. Also, do not use the words the year in front of the year (1999, not the year 1999). Use numerals, not words (1999, not Nineteen ninety-nine).
  • Decades should not contain an apostrophe (1920s, not 1920's) and avoid the two digit version of this ('20s) unless it is clear what century it is in the context of article.

Usage

Possessives

Pronouns

Contractions

Language and spelling

Images

Images are an important way to make the CPAPtalk.com CPAP Wiki better. Here are a few guidelines:

  • Typically an article will start with an image on the right hand side of the page (right-alignment).
  • If multiple images are used in one article, they may be staggered left and right.
  • Do not sandwich text copy between two images.
  • Usually images of faces should be placed so they are looking towards the text.
  • Use a caption to explain the relevance of the image to the article.
  • Place images where they are relevant to the text next to, or near it, when possible.
  • If there are a lot of images, consider using a gallery so as not to clutter up the article.
  • The easiest "wiki markup language", or format for images is:
[[Image:picture.jpg|thumb|[width in number of pixels]px|right|Insert caption here]]

More help with images, is available.

Captions

Usage
Images placed in an article should almost always have a caption explaining the relevance of the image to the article.
Formatting
  • Start captions with a capital letter, in most cases.
  • Most captions are not complete sentences, but are usually sentence fragments that should not end with a period. If a complete sentence is formed in a caption, that sentence should end with a period.
  • Do not use italics, unless a word is normally italicized.
  • Typically, a caption should be relatively short (10 words or less).

Bulleted and numbered lists

Use a numbered list only if there is some value added by having a numbered list. For example: Sequence of the list is important, explaining step-by-step instructions, or the need to refer to the elements by number.

  • Do not use bullets or numbered lists if the passage reads well using normal paragraphs.
  • Use the same grammatical style within the list.
    • Use full sentences or fragments but not both.
    • Place a period at the end of full sentences, and no period at the end of fragments.

Links

In general, links should not make an article more difficult to read. Rather, they should serve as a navigational tool to find more information.

Wikilinks

Wikilinks are links that go to another page, section, or article inside the wiki. They are different than external links which go to another website on the internet. Overlinking an article makes it difficult to read, draws attention away from relevant terms in the article, and makes maintenance more difficult.

Here are some guidelines for wikilinks:

  • Only link a word the first time it is used in the article. Do not link the same word more than once in an article, unless it is a very long article, or there is some relevant reason to link the word again, after the first occurrence.
  • Link only relevant words in the context of the article. In other words, do not link every possible word that could be linked. Just link words that are important to the article, or that a reader may need to know more about to understand the article.<p
  • Check links to make sure they go to the correct place. If the link goes to a disambiguation page, it is better to link to the correct page. If the link goes to a page, but should link to a section on that page, then link to the correct section.

Miscellaneous

See also

CPAPtalk.com CPAP Wiki Help

== External links ==