MeritBadgeDotOrg:Manual of Style

From MeritBadgeDotOrg

Revision as of 08:13, April 22, 2008 by Scouterdennis (Talk | contribs)
Jump to: navigation, search

Template:Guideline This Manual of Style is to help make MeritBadgeDotOrg easier to read by having rules for its format. It is a style guide. The rules on this page are not the final word on MeritBadgeDotOrg style. One way is often as good as another, but if everyone does things the same way, MeritBadgeDotOrg will be easier to read and use, and easier to write and edit. These are not laws: they are rules that many editors have found to work well in most cases. Editors should try to have their articles follow these guidelines, but remember, often there is "an exception to every rule", so also use common sense above all.

One of the great things about editing a wiki is that edits do not have to be perfect -- they can always be changed, improved or corrected later on. Wikipedia does not require writers to follow all or any of these rules, but their efforts will be more appreciated when they use this guide.

Contents

Article titles

In picking the best article title, remember these guidelines:

  • Use the singular. For example, if you added a new article about cars, you would name it "Car", not "Cars". (This rule is different for making categories, though.)
  • Use English. If you make a new article about the capital of Russia, you would name it "Moscow", not "Moskva".
  • Do not use abbreviations. An article on the World Health Organization should not be titled "WHO".

Don't worry if the wrong name is chosen for an article - it can always be moved, and this automatically creates a redirect from the older entry. Redirects should also be made from all other entries someone might type when looking for your article.

Places

  • Countries should usually be listed under their simple name, not their full name, for example Ethiopia, not Federal Democratic Republic of Ethiopia.
  • For places inside countries or states, the name of the country or state can appear after a comma and space, especially if there is more than one place of that name. Example: Scottsdale, Arizona.

The first sentence

If possible, make the article's topic (usually the same as its title) the subject of the first sentence of the article (instead of putting it in the predicate, or in another sentence). For example, write "This Manual of Style is a style guide", not "This style guide is known as..." .

If the article's title is an important word, use it as early as possible in the article. Bold the article title the first (and only the first) time it is used. Also, bold any important synonyms - other names for the same thing, or older names. Use three apostrophes to make the bold: '''article title''' will appear as article title</span>.

This example shows how bold words are used in an article on the Byzantine Empire:

The Byzantine Empire (or Eastern Roman Empire) is the name given to the Roman Empire that existed during the Middle Ages.

Do not bold any other words in the first paragraph, so that the reader will not be confused.

It is usually better not to link any of the bold title words and synonyms. For example, do not write "The Byzantine Empire is..."

Things like names of books, movies, or foreign words are usually put in italics, and can be combined with the bold text, for example:

Citizen Kane is a movie from 1941, starring Orson Welles in his first full-length movie.

Sections and headings

Markup

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

This section’s heading was created by writing:

==Sections and headings==

This subsection’s heading was created by writing:

===Markup===

Wording

  • In a heading, capitalize only the first letter of the first word and the first letter of any proper nouns, and leave all of the other letters in lowercase. Example: "Rules and regulations", not "Rules and Regulations".
  • Do not use special characters in headings, such as a slash (/), a plus sign (+), curly braces ({}), or square braces ([]). In place of an ampersand (&) use the word and, unless the ampersand is part of a formal name.
  • Do not put links in headings. Instead, link the word or phrase the first time it appears in the section.
  • Keep the heading short. Try not to use more than ten words in the heading.
  • Try not to use extra words in headings if they aren't needed, such as a, an, the, and pronouns. Do not use the title of the whole article as a heading.
  • Do not give the same title to different sections. This will confuse the reader. It also makes it difficult for any editor to create a section link to any such section except the first one.

Creating and using sections

Sub-headings help readers quickly see what is covered in an article and find subtopics of interest. Create sub-headings if a section becomes too long, and choose a wording that describes what is discussed in the section.

  • Do not italicize the section name, unless it needs italics (for example, if it is the title of a book).
  • If you link directly to a section, leave an editor’s note to remind others that the section title is linked. List the names of the linking articles, so when the title needs changing, others can fix the links more easily. For example: <!-- This section is linked from [[Richard Dawkins]] and [[Daniel Dennett]] --> .
  • Try not to change section headings and sub-headings too often. Other articles may have linked to that section, and the section link will be broken.

Capital letters

Do not capitalize the first letter in a word or the entire word to add importance to it. For example, "aardvarks, which are Not The Same as anteaters" and "aardvarks, which are NOT THE SAME as anteaters" are both wrong. If a word needs to show added importance or emphasis, use italics ("aardvarks, which are not the same as anteaters").

Italics

For italics, use the '' (italic) markup on both sides of the text to be italicized. For, example:

''This is italic.''

will give:

This is italic.

Effect on nearby punctuation and links

In all of the uses mentioned here, italicize only what should properly be affected by italics, and not the surrounding punctuation of the sentence. Examples:

  • What are we to make of that?
[Incorrect: only the word that should be italicized; the following question mark should not be italicized.]
  • The word was tack; it certainly was not tick, tap, or tab.
[Correct: the punctuation marks here are not italicized; they are normal parts of the sentence.]

If an italicized word or phrase is linked, the italics markup should be placed outside of the link markup, otherwise you will get a "redlink". Example:

  • ''[[Jurassic Park]]'' is [[Michael Crichton]]'s best book.
[Correct: it will show the text with a correct link: "Jurassic Park is Michael Crichton's best book."]

Emphasis

Italics are mainly used to emphasize (show importance of) certain words. Italics for emphasis should not be used too often.

They are also used in these other cases:

Titles

Italics are used for the titles of works of literature and art, such as books, movies, albums and paintings. The titles of articles, chapters, songs, and other short works are not italicized; instead they are put in double quotation marks ("Chapter Title").

Words as words

Use italics when writing about words as words, or letters as letters. For example:

  • Deuce means “two”.
  • The word liqueur comes from the Latin word liquifacere.
  • The most common letter in the English language is e.
  • In English class I received an A.

Quotations in italics

Do not put an entire quotation in italics just because it is a quotation.

Acronyms and abbreviations

Do not assume that your reader knows the acronym or abbreviation you are using. The acronym or abbreviation should be spelled out the first time it is used (wikilinked if appropriate) and then show the acronym or abbreviation after it, in parentheses. For example:

The United Kingdom Independence Party (UKIP) is a political party that wants Britain to leave the European Union. There are currently about 25,000 people who are members of the UKIP.

If the term is already in parentheses, use or to indicate the acronym. For example:

It was first discussed in 2006 (at a meeting for the members of the United Kingdom Independence Party or UKIP).

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

  • More than one CD-ROM are CD-ROMs
  • More than one NGO are NGOs

Punctuation

In most cases, follow the usual rules of English punctuation. A few points where MeritBadgeDotOrg may be different from usual rules are listed below.

Quotations and quote marks

Whenever possible, faithfully use the same style that was used in the original quotation; do not change it to follow MeritBadgeDotOrg's rules on punctuation. If there is a spelling or other mistake in the original quote, it can be noted with [sic].

The guideline is to use the double-quotes (" ") – they are easier to read on the screen – and use single-quotes (‘ ’) for quotations that are within quotations. Quotation marks that are next to each other should be separated by a space. This best way to do this is to type &nbsp;.

For example, you might quote an article that says, "She disputed his statement that ‘Voltaire never said "I disapprove of what you say, but I will defend to the death your right to say it" ’ ". (Note that quote marks that are next to each other, as at the end of this example, should always have a space between them. This should be done by typing &nbsp; instead of a normal space.)

When punctuating quoted passages, put the punctuation mark inside the quotation marks only if the sense of the punctuation mark is part of the quotation (logical quotations).

Examples:

  • Arthur said the situation is "deplorable". (When part of a sentence is quoted, the period/full stop is outside.)
  • Arthur said, "The situation is deplorable." (When a complete sentence is quoted, the period is inside.)
  • Martha asked, "Are you coming?" (When quoting a question, the question mark is inside.)
  • Did Martha say, "Come with me"? (When questioning a quote, the question mark is outside. Do not use a period.)

If you change the capitalization of the first letter of a quote, you do not need to "[s]how the case change with square brackets".

Here are two examples from the Chicago Manual of Style that show how to handle commas and capital letters at the beginning of a quote within a sentence:

He said that "to have is to hold". She said, "Go now".

Words inside quotes can be linked, for example: (quoted from John Adams) "If Aristotle, Livy, and Harrington knew what a republic was, the British constitution is much more like a republic than an empire."

Except with well-known quotations (from Shakespeare etc.), and those from the subject of the article or section, always name the person you are quoting for a full sentence or more. Name the person in the text, not in a footnote, unless the person is the subject of the article or is otherwise obvious. In the case of a famous line from a play in an article on the play, it is not necessary to say the quote is from the play.

When the title of an article needs quotation marks (for example, the title of a song or poem), the quotation marks should not be bolded, because they are not part of the title:

"Jabberwocky" is a nonsense poem by Lewis Carroll.

Longer quotes

A quote longer than four lines should be written as a block quotation. Do not put the block quote in quotation marks. To do a block quotation, do not use the wiki indentation mark : – instead, use the HTML <blockquote> tag:

<blockquote>
Four score and seven years ago, our fathers brought forth on this continent a 
new nation, conceived in Liberty, and dedicated to the proposition that all men 
are created equal.
</blockquote>

Result:

Four score and seven years ago, our fathers brought forth on this continent a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.

Because of a bug in the site’s software, <blockquote> does not yet properly format quotes that are longer than one paragraph. Until this is fixed, you may add <p> tags around paragraphs:

<blockquote>
<p>First paragraph</p>

<p>Second paragraph</p>
</blockquote>


Look of quotation marks and apostrophes

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

  • text, text, foos
  • "text", 'text', foo's

Either way is okay. Never use grave and acute accents or backticks (`text´) as quotation marks or apostrophes.

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 not using a serial comma makes an unclear sentence, as in this example: "The author would like to thank her parents, Sinéad O’Connor and President Bush." Sometimes using the comma can also make a sentence unclear, as in: "The author would like to thank her mother, Sinéad O’Connor, and President Bush" which may be a list of either two or three people. In such cases, there are three options to make the sentence more clear:

  • A choice can be made whether or not to use the comma.
  • The sentence can be rewritten to avoid listing the items in an unclear way.
  • The items in the list can be presented using a formatted list.

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.

Spaces after the end of a sentence

There are no guidelines on whether to use one space after the end of a sentence, or two. The issue is not important because the difference can only be seen in the edit box.

Contractions

Do not use contractions—such as don’t, can’t, won’t, would’ve, they’d, and so on—unless they are in a quotation.

Slashes

Try not to join two words with a slash (/), because it suggests that the two are related, but does not say exactly how. There is almost always a better choice than a slash. When it is possible, be specific to avoid wording that is not clear.

An example: "The parent/instructor must be present at all times." Must both be present? (Then write and say "the parent and the instructor".) Must at least one be present? (Then write and say "the parent or the instructor".) Is it intended that the same person is both parent and instructor? (Then use an en dash or a hyphen: "the parent–instructor".)

In situations involving a distinction or disjunction, the en dash is usually better than the slash, for example, "the novel–novella distinction".

The slash does have some good uses. It can be used to separate lines of poetry ("To be or not to be: that is the question: / Whether 'tis nobler in the mind to suffer / The slings and arrows of outrageous fortune") or to show how something is spoken or pronounced ("ribald is pronounced /ri-bəld/" or to separate the numbers in a fraction ("Template:Frac").

"And/or"

The phrase and/or is especially awkward. For example, "x and/or y" can be written as "x or y, or both", or "either x or y" and optionally add "but not both", if necessary.

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 clear; but with more than two it may difficult to know what is trying to be expressed. Instead of "x, y, and/or z", use an appropriate alternative: "one or more of x, y, and z"; "some or all of x, y, and z"; etc.

Simple tables

Lines that start with blank spaces in the editing window are shown in a box, like this:

A line with a blank space in front of it.

Many lines with a space in front will create a table, like this:

line 1
line 2
line 3

A line that contains only a blank space inserts a blank line into the table.

line 1

line 2

Images

These are some general guidelines which are usually followed for the best appearance, although some editors have different ideas:

  • Articles usually start with an image on the right-hand side of the page (this is called right-alignment).
  • When using many images in the same article, they can be placed on either the right or left side of the page.
  • Avoid sandwiching text between two images directly across from each other.
  • Generally, right-alignment is preferred to left- or center-alignment. It is okay for all the pictures in an article to be on the right side of the page.
  • If there are very many images in a given article, consider using a gallery.
  • The easiest "image markup language", or format for images is:
[[Image:picture.jpg|thumb|[width in number of pixels]px|right|Insert caption here]]
  • Use captions to explain how the image relates to the article. The caption will not show up unless you use "thumb" format in the image markup language. Any caption should start with a capital letter. If the caption is a complete sentence, it should always end in a period (or other appropriate punctuation). If the caption is not a complete sentence, it should not have a period at the end.
  • Putting the size of a thumb image in the formatting is not necessary: if the size is not put in the formatting, the width will be the size that the reader has set in their settings, with a default of 180px.
  • The default placement of a thumb image is "right" if none is given, so it is not necessary to include "right", but it must be replaced by "left" (or "center") to appear elsewhere.
  • Remember that people looking for more information on the photo can click on it to see the full details.

Bulleted lists and numbered lists

If a line begins with the asterisk (*), it will appear as a bullet, which can make lists of things much easier to read. Make sure there is no space before the bullet, or the whole sentence will appear in a box instead.

Do not use bullets (*) if the article reads easily using plain paragraphs.

Do not mix grammatical styles in a list – either use all complete sentences, or use all sentence fragments. Begin each item with a capital letter, even if it is a sentence fragment.

When using complete sentences, put a period at the end of each sentence:

  • This is a complete sentence.
  • This is also a complete sentence.

When using sentence fragments, do not put a period at the end:

  • Part of a sentence
  • Also a sentence fragment

The rules for bulleted lists are the the same for numbered lists. You can start every section with the pound (#) sign and the wiki will number the section on its own.

Nesting numbered lists

If using the pound (#) sign and there are subsections, you can use the colon (:) after the (#) to indent the subsection, which will allow the list numbering to continue as normal with the subsequent item.

For example, using:

# requirement 1
# requirement 2
#:a. requirement 2a
#:b. requirement 2b
#:c. requirement 2c
# requirement 3
# requirement 4
# requirement 5

Will produce:

  1. requirement 1
  2. requirement 2
    a. requirement 2a
    b. requirement 2b
    c. requirement 2c
  3. requirement 3
  4. requirement 4
  5. requirement 5

Wikilinking

Links should not make an article more difficult to read; they are there for making it easier to find related information.

Only link the things and ideas that are important to understanding the article. It is not helpful to mark all possible words as hyperlinks. A large number of links can draw attention away from the most important links on a page.

Only link a word the first time it is used in the article, but do not link the same word more than once in an article.

Check links after they are wikified, to make sure they lead to the correct page.

When including wikilinks in an article, there is no need to capitalize the first word. Wikilinks that begin sentences or are proper nouns should be capitalized as normal.

Piped links can also be avoided in many cases when adding a suffix to a wikilink that is not part of an article title, by placing the suffix outside of the brackets. The suffix will still appear as part of the link, but will not be included in the link's target when actually clicked. For example, the markup [[apple]]s will be in the article text as apples, but it links to the article Apple.

Miscellaneous notes

Keep markup simple

Use the simplest markup to display information in a useful and easy-to-understand way. Markup may appear differently in different browsers. Only use HTML and CSS markup if there is a good reason. Use wikimarkup whenever possible.

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 used in articles except in special cases. If you must use a different font size, use a relative size, such as font-size: 80%; not an absolute size, for example, font-size: 8pt. Do not use other style changes, such as font style or color.

Color coding

Using color alone to convey information (color coding) should not be done. This is not helpful to people with color blindness (especially monochromacy), on black-and-white printouts, on older monitors with fewer colors, on monochrome displays (Personal digital assistants, cell phones), etc.

If it is necessary to use colors, try to choose colors that will not be confusing to a person with red-green color blindness (the most common type). In general, this means that shades of red and green should not both be used as color codes in the same image. Colors that are okay to use include orange and violet. Viewing the page with Vischeck can help with deciding if the colors should be changed.

It is nice to use color as an aid for those who can see it, but the information should still be available without it.

Invisible comments

Invisible comments are used to talk with other editors in the article body. These comments can only be seen when editing the page. They are invisible when looking at the normal article.

Usually, if an editor wants to discuss something with other editors, he or she will do it on the proper talk page. However, it is sometimes useful to put comments directly in the article, because an editor would like to leave instructions to help other editors when they edit a section, or leave reminders about something (for example, "please do not change the section title, since others have linked here").

To leave a hidden comment, place the words between these "spearpoints": <!-- and -->.

For example, the following:

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

is shown as:

Hello world.

Legibility

Consider the legibility of what you are writing. Make your entry easy to read on a screen. For more information on this, see "How Users Read on the Web" by Jakob Nielsen.

External links

Links to websites outside of MeritBadge.org should be listed at the end of an article or in the text of an article as an "embedded link".

List of links at the end of an article ("External links")

A list of links should have a header named == External links ==, followed by a bulleted list of links. It is good if a link on the list summarizes the website's contents, and tells why the website is important to the article. For example:

*[http://www.aidsnews.org/ AIDS treatment news]

Embedded links

External links can also be "embedded" directly within an article. These links generally have no description, but they will automatically be given a number by the software. For example, typing:

Sample text [http://www.example.org].

will show the link as:

Sample text [1].

An embedded external link should have a full citation in the article's References section.

References or Notes

The References or Notes section can have a code that will copy your embedded link (with its external link, description and/or quote) into the References or Notes section, and make it a functioning link there. Do not use this code with an embedded link alone. Use it only if you're adding a citation or description of the link.

Here is an example:

The embedded link format would look like this:

<ref name="test1">[http://www.example.org/ The name of the other website goes here.] More information can go here.</ref>

It will produce this: [1]


Then in the "References" or "Notes" section, the code would look like this:

<references />

Using this code will automatically copy the same embedded link you have made above:

  1. The name of the other website goes here. More information can go here.

You can also use the template {{reflist}} to give the same as above, but with a smaller font size. For a two-column layout, use {{reflist|2}}.

External links

Writing guides
Guide to Layout Manual of Style
How to structure articles Comprehensive style guide
Personal tools
language