FlightGear wiki:Manual of Style

From FlightGear wiki
Jump to navigation Jump to search

Shortcut
FGW:MOS


The Manual of Style is a style manual for all FlightGear wiki articles. It helps editors write articles with consistent, clear, and precise language, layout, and formatting. The goal is to make using this wiki easier and more intuitive. Consistent language, style, and formatting promote clarity and cohesion. Writing should be clear and concise. Plain English works best; avoid ambiguity, jargon, and vague or unnecessarily complex wording.

Discuss style issues on the talk page.

Article titles, headings, and sections

Article titles

  • Use sentence case, not title case. The initial letter of a title is capitalized (except in rare cases, such as eBay), but otherwise, capital letters are used only where they would be used in a normal sentence (List of developed airports, not List of Developed Airports). Also, keep in mind that the wiki software automatically capitalizes the initial letter of a namespace/page title in its address.
  • Titles should be precise enough to unambiguously define the topical scope of the article (Boeing 747, not 747).
  • The characters # < > [ ] | { } are reserved by the wiki software and can not be used.

Section organization

An article should begin with an introductory lead section, which should not contain section headings. The remainder may be divided into sections, each with a section heading (see below) that can be nested in a hierarchy. If there are at least four section headings in the article, a navigable table of contents is generated automatically and displayed between the lead and the first heading.

Section headings

Equal signs are used to mark the enclosed text as a section heading: == Title == for a primary section; === Title === for the next level (a subsection); and so on to the lowest-level subsection, with ===== Title =====. (The highest heading level technically possible is = Title =; but do not use it in articles, because it is reserved for the automatically generated top-level heading at the top of the page containing the title of the whole article.) Spaces between the equal signs and the heading text are optional, and will not affect the way the heading is displayed. The heading must be typed on a separate line. Include one blank line above the heading, and optionally one blank line below it, for readability in the edit window (but not two or more consecutive blank lines, which will add unnecessary visible white space in the rendered page.)

The provisions in Article titles (above) generally apply to section headings as well (for example, headings are in sentence case, not title case). The following points apply specifically to section headings:

  • Headings should normally not contain links, especially where only part of a heading is linked.
  • Section and subsection headings should preferably be unique within a page; otherwise section links may lead to the wrong place, and automatic edit summaries can be ambiguous.
  • Citations should not be placed within or on the same line as section and subsection headings.
  • Headings should not contain images.

Capital letters

Sentence case rather than title case is used in wiki article titles and section headings; see Article titles and Section headings above. For capitalization of list items, see Bulleted and numbered lists. Other points concerning capitalization are summarized below.

Do not use capitals for emphasis

Use italics, not capitals, to denote emphasis.

Incorrect: It is not only a LITTLE learning that is dangerous.
Correct: It is not only a little learning that is dangerous.

Calendar items

  • Months, days of the week, and holidays start with a capital letter (June, Monday).

Celestial bodies

  • When used generally, the words sun, earth, and moon do not take capitals (The sun was peeking over the mountain top), except when the term names a specific astronomical body (The Moon orbits the Earth).

Compass points

Do not capitalize directions such as north, nor their related forms (Follow the northern road), except where they are parts of proper names (such as South Pole).

Capitalize names of regions if they have attained proper-name status, including informal conventional names (Southern California or the Western Desert). Do not capitalize descriptive names for regions that have not attained the status of proper names, such as southern Poland.

(Composite directions may or may not be hyphenated, depending on the style adopted in the article. Southeast Asia and northwest are more common in American English; but South-East Asia and north-west in British English. In cases such as north–south dialogue and east–west orientation an en dash is used.)

Abbreviations

Write out both the full version and the abbreviation at first occurrence

  • When an abbreviation is to be used in an article, give the expression in full at first, followed immediately by the abbreviation in parentheses (round brackets). In the rest of the article the abbreviation can then be used by itself:
The instrument landing system (ILS) is a ground-based instrument approach system, at the first mention of the instrument landing system; and
There are three categories of ILS, at a subsequent mention.
  • Do not apply initial capitals in a full version simply because capitals are used in the abbreviation.
Correct: There are two types of flight rules: visual flight rules (VFR) and instrument flight rules (IFR).
Incorrect: There are two types of flight rules: Visual Flight Rules (VFR) and Instrument Flight Rules (IFR).

Ampersand

The ampersand (&) substitutes for the word and (it is a form of Latin et). In normal text, and should be used instead: version 1 and 2, not version 1 & 2. Ampersands may be used with consistency and discretion in tables, infoboxes, and similar contexts where space is limited.

Italics

Emphasis

Italics may be used sparingly to emphasize words in sentences (whereas boldface is normally not used for this purpose). Generally, the more highlighting in an article, the less its effectiveness.

Quotations in italics

Quotations must always be clearly indicated as being quotations. For quotations, use only quotation marks (for short quotations) or block quoting (for long ones), not italics. (See Quotations below.) This means that (1) a quotation is not italicized inside quotation marks or a block quote just because it is a quotation, and (2) italics are no substitute for proper quotation formatting.

Quotations

Where the same quotation has been used elsewhere in the article, avoid duplicating it, which is regarded as poor style.

The quotation should be representative of the whole source document; editors should be very careful to avoid misrepresentation of the argument in the source. Where a quotation presents rhetorical language in place of more neutral, dispassionate tone preferred for encyclopedias, it can be a backdoor method of inserting a non-neutral treatment of a controversial subject into the wiki's narrative on the subject, and should be avoided.

Quotations should generally be worked into the article text, so as not to inhibit the pace, flow and organization of the article. Longer quotes may need to be set apart, generally through the use of wikitext templates such as {{Quote}} or {{Quotation}}. Longer quotations may also be hidden in the reference (footnote) to facilitate verification by other editors without sacrificing readability. For pull quotes (quotes of the article text used to highlight a section) the {{Cquote}} template can be used. Quotations used only as sources to support statements contained in the article can be added with a <ref> tag containing a reference formatted with the {{cite web}} template; in that case, add {{Appendix}} at the end of the page so that citations can be displayed in a uniform way.

Original wording

Quotations must be verifiably attributed and the wording of the quoted text should be faithfully reproduced. If there is a significant error in the original statement, use [sic] to show that the error was not made by the wiki editors. However, trivial spelling and typographic errors should simply be corrected without comment (for example, correct basicly to basically), unless the slip is textually important.

Use ellipses to indicate omissions from quoted text. Legitimate omissions include extraneous, irrelevant, or parenthetical words. Do not omit text where doing so would remove important context or alter the meaning of the text.

Typographic conformity

In most cases it is not desirable to duplicate the original formatting. Formatting and other purely typographical elements of quoted text should be adapted to the wiki's conventions without comment provided that doing so will not change or obscure the meaning of the text. These are alterations which make no difference when the text is read aloud, such as:

  • Changing capitalization so that sentences begin with capital letters.
  • When quoting a quotation that itself contains a quotation, single quotes may be replaced with double quotes, and vice versa. See Quotations within quotations below.
  • Removing spaces before punctuation such as periods and colons.
  • Generally preserve bold and italics (see Italics, above), but most other styling should be altered.
  • Expanding abbreviations.

Quotations within quotations

For quotations within quotations, use double quote marks outermost and, working inward, alternate single with double quote marks.

Attribution

The author of a quote of a full sentence or more should be named; this is done in the main text and not in a footnote. A reader should not have to follow a footnote to learn whose words a quote is.

Linking

As much as possible, avoid linking from within quotes, which may clutter the quotation, violate the principle of leaving quotations unchanged, and mislead or confuse the reader.

Block quotations

Format a long quote (more than about 40 words or a few hundred characters, or consisting of more than one paragraph, regardless of length) as a block quotation, which the wiki's software will indent from both margins. Do not enclose block quotations in quotation marks (and especially avoid decorative quotation marks in normal use, such as those provided by the {{cquote}} template, which are reserved for pull quotes; quoted sections from elsewhere in the same wiki article). Block quotations can be added with {{quote}} or {{quotation}}.

Overusing quotations

Long quotations crowd the actual article and remove attention from other information. Many direct quotations can be minimized in length by providing an appropriate context in the surrounding text. A summary or paraphrase of a quotation is often better where the original wording could be improved. Consider minimizing the length of a quotation by paraphrasing, by working smaller portions of quotation into the article text, or both.

Overuse happens when:

a quotation is used without pertinence

This means that a quotation is visually on the page, but its relevance is not explained anywhere.

Specific recommendations

  • Using too many quotes is incompatible with the encyclopedic writing style.
  • As a matter of style, quoteboxes should generally be avoided as they draw special attention to the opinion of one source, and present that opinion as though the project endorses it. Instead of using quoteboxes to highlight its notability, explain its importance before introducing the quote or in an introduction to the quote.
  • The wiki is not a list or repository of loosely associated topics such as quotations.
  • Do not insert any number of quotations in a stand-alone quote section.
  • A quotation that does not directly relate to the topic of the article or directly support the information as it is presented should not be used.
  • Intersperse quotations with original prose that comments on those quotations instead of constructing articles out of quotations with little or no original prose.
  • Longer quotations may be hidden in the reference as a footnote to facilitate verification by other editors without sacrificing readability.

Punctuation

Apostrophes

  • Consistent use of the straight (or typewriter) apostrophe ( ' ) is recommended, as opposed to the curly (or typographic) apostrophe ( ’ ).

Quotation marks

Double or single
Enclose quotations with double quotation marks (Bob said, "Jim ate the apple."). Enclose quotations inside quotations with single quotation marks (Bob said, "Did Jim say 'I ate the apple' after he left?").
Block quotes
As already noted above, we use quotation marks or block quotes (not both) to distinguish long quotations from other text. Multiparagraph quotations are always block-quoted. The quotations must be precise and exactly as in the source (except for certain allowable typographical changes, also noted above). The source should be cited clearly and precisely.

Brackets and parentheses

These rules apply to both round brackets ( ), often called parentheses, and square brackets [ ].

If a sentence contains a bracketed phrase, place the sentence punctuation outside the brackets (as shown here). However, where one or more sentences are wholly inside brackets, place their punctuation inside the brackets. There should be no space next to the inner side of a bracket. An opening bracket should usually be preceded by a space, for example. This may not be the case if it is preceded by an opening quotation mark, another opening bracket, or a portion of a word.

There should be a space after a closing bracket, except where a punctuation mark follows (though a spaced dash would still be spaced after a closing bracket) and in unusual cases similar to those listed for opening brackets.

If sets of brackets are nested, use different types for adjacent levels of nesting; for two levels, it is customary to have square brackets appear within round brackets. This is often a sign of excessively convoluted expression; it is often better to recast, linking the thoughts with commas, semicolons, colons, or dashes.

Avoid adjacent sets of brackets. Either put the parenthetic phrases in one set separated by commas, or rewrite the sentence.

Square brackets are used to indicate editorial replacements and insertions within quotations, though this should never alter the intended meaning. They serve three main purposes.

Sentences and brackets

  • If any sentence includes material that is enclosed in square or round brackets, it still must end—with a period, or a question or exclamation mark—after those brackets. This principle applies no matter what punctuation is used within the brackets.
  • However, if the entire sentence is within brackets, the closing punctuation falls within the brackets. (This sentence is an example.) This does not apply to matter that is added (or modified editorially) at the beginning of a sentence for clarity, which is usually in square brackets.

Ellipses

An ellipsis (plural ellipses) is used to indicate an omission of material from quoted text or some other omission, perhaps of the end of a sentence, often in a printed record of conversation. The ellipsis is represented by ellipsis points: a set of three unspaced periods, surrounded by square brackets [...].

Dates and time

Time of day

Time of day is normally expressed in figures rather than being spelled out. Context determines whether the 12- or 24-hour clock is used.

  • 12-hour clock times are written in the form 11:15 a.m. and 2:30 p.m., or the form 11:15 am and 2:30 pm, with a space before the abbreviation.
  • 24-hour clock times are written in the form 08:15, 22:55, with no suffix. Note that 00:00 refers to midnight at the start of a date, and 24:00 to midnight at the end of a date.

Days

  • For full dates, use the format 10 June 1921 or the format June 10, 1921. Similarly, where the year is omitted, use 10 June or June 10. For choice of format, see below.
  • Do not use numerical date formats such as 03/04/2005, as this could refer to 3 April or to March 4. If a numerical format is required (e.g. for conciseness in long lists and tables), use the YYYY-MM-DD format: 2005-04-03.

Choice of format

  • All the dates in a given article should have the same format (day-month or month-day). These requirements do not apply to dates in quotations or titles.
  • Otherwise, do not change an article from one form to another without good reason.

Months

  • For month and year, write June 1921, with no comma.
  • Abbreviations for months, such as Feb, are used only where space is extremely limited. Such abbreviations should use three letters only, and should not be followed by a period (full stop) except at the end of a sentence.

Years and longer periods

  • Do not use the year before the digits (1995, not the year 1995), unless the meaning would otherwise be unclear.
  • Decades are written in the format the 1980s, with no apostrophe. Use the two-digit form ('80s) only with an established social or cultural meaning. Avoid forms such as the 1700s that could refer to 10 or 100 years.

Current

Use of the term "current" should be avoided. What is current today may not be tomorrow; situations change over time. Instead, use date- and time-specific text.

Incorrect: FlightGear 3.0 is currently the latest version ...
Correct: As of February 2014, FlightGear 3.0 is the latest version ...

Numbers

  • In general, write whole numbers from one to nine as words, write other numbers that take two words or fewer to say as either figures or words (with consistency within each article), and write all other numbers as figures: 1/5 or one-fifth, 84 or eighty-four, 200 or two hundred, but 3.75, 544, 21 million.
  • In general, use a comma to delimit numbers with five or more digits to the left of the decimal point. Numbers with four digits are at the editor's discretion: 12,345, but either 1,000 or 1000.
  • In general, use decimals rather than vulgar fractions with measurements.
  • Write out "million" and "billion" on the first use. After that, unspaced "M" can be used for millions and "bn" for billions: 70M and 25bn.
  • Write 3%, three percent, or three per cent, but not 3 % (with a space) or three %. "Percent" is American usage, and "per cent" is British usage. In ranges of percentages written with an en dash, write only one percent sign: 3–14%.

Units of measurement

  • The main unit in which a quantity is expressed should generally be an SI unit or non-SI unit officially accepted for use with the SI.
  • In a direct quotation, always keep the source units. If a conversion is required, it should appear within square brackets in the quote, or else an obscure use of units can be explained in a footnote.
  • Where space is limited (such as tables, infoboxes, parenthetical notes, and mathematical formulas) use unit symbols. In main text it is usually better to spell out unit names, but symbols may also be used when a unit (especially one with a long name) is used repeatedly. However, spell out the first instance of each unit in an article (for example, the typical batch is 250 kilograms ... and then 15 kg of emulsifier is added), except for unit names that are hardly ever spelled out (e.g. the degree Celsius). Most unit names are not capitalized. Use "per" when writing out a unit, rather than a slash: meter per second, not meter/second.
  • Potentially unfamiliar unit symbols should be introduced parenthetically at their first occurrence in the article, with the full name given first: for example, His initial betatron reached energies of 2.3 megaelectronvolts (MeV), while subsequent betatrons achieved 300 MeV.
  • When dimensions are given, each number should be followed by a unit name or symbol (e.g. write 1 m × 3 m × 6 m, not 1 × 3 × 6 m).
  • When they form a compound adjective, values and unit names should be separated by a hyphen: for example, a five-day race.
  • Unit symbols are preceded by figures, not by spelled-out numbers. Values and unit symbols are separated by a non-breaking space. For example, 5 min. The percent sign, and units of degrees, minutes, and seconds for angles and coordinates, are unspaced.
  • Standard unit symbols do not require a full stop (period). However non-standard abbreviations should always be given a full stop.
  • No s is appended, e.g. km, in, lb, not kms, ins, lbs.
  • Write powers of unit symbols with HTML, e.g. 5 km<sup>2</sup> not Unicode superscripts and subscripts.
  • For quantities of bytes and bits, specify whether the binary or decimal meanings of K, M, G, etc. are intended.

Grammar and usage

First-person pronouns

Wiki articles must not be based on one person's opinions or experiences. The use of I, my, or similar forms is restricted to user pages and quotations. Also avoid we, us, and our: We should note that some critics have argued against our proposal (personal rather than encyclopedic).

Vocabulary

Contractions

Uncontracted forms such as do not or it is are the default in encyclopedic style; don't and it's are too informal.

Foreign terms

Foreign words should be used sparingly.

No common usage in English

Use italics for phrases in other languages and for isolated foreign words that are not current in English.

Common usage in English

Loanwords and borrowed phrases that have common usage in English (vice versa) do not require italics. A rule of thumb is not to italicize words that appear unitalicized in major English-language dictionaries.

Technical language

Some topics are intrinsically technical, but editors should try to make them understandable to as many readers as possible. Minimize jargon, or at least explain it. For unavoidably technical articles a separate introductory article may be the best solution. Avoid excessive wikilinking (linking within the wiki) as a substitute for parenthetic explanations such as the one in this sentence. Do not introduce new and specialized words simply to teach them to the reader when more common alternatives will do. When the notions named by jargon are too complex to concisely explain in a few parenthetical words, write one level down. For example, consider adding a brief background section with {{main}} tags pointing to the full treatment article(s) of the prerequisite notions; this approach is practical only when the prerequisite concepts are central to the exposition of the article's main topic, and when such prerequisites aren't too numerous.

Geographical items

Places should generally be referred to consistently by the same name as in the title of their article. Exceptions are made if there is a widely accepted historical English name appropriate to the given context. In cases where such a historical name is used, it should be followed by the modern name in round brackets (parentheses) on the first occurrence of the name in applicable sections of the article. This resembles linking; it should not be done to the detriment of style. On the other hand, it is probably better to provide such a variant too often than too rarely. If more than one historical name is applicable for a given context, the other names should be added after the modern English name, that is: "historical name (modern name, other historical names)".

Images

  • Infoboxes, images, and related content in the lead must be right-aligned.
  • Use captions to clarify the relevance of the image to the article (see Captions, below).
  • Each image should be inside the major section to which it relates (within the section defined by the most recent level 2 heading or at the top of the lead), not immediately above the section heading.
  • Avoid sandwiching text between two images that face each other, and between an image and an infobox or similar.
  • The thumbnail option may be used ("thumb"), or another size may be fixed. The default thumbnail width is 220 pixels; users can adjust this in their preferences. Lead images should be no wider than "upright=1.35" (by default this is 300 pixels).
  • Avoid referring to images as being on the left or right. Image placement is different for viewers of the mobile version of the wiki and might change in the future. Instead, use captions to identify images.

Avoid entering textual information as images

Textual information should almost always be entered as text rather than as an image. True text can be colored and adjusted with CSS tags and templates, but text in images cannot be. Images are not searchable and are slower to download. Any important textual information in an image should also appear in the image's alt text, caption, or other nearby text.

Captions

Photographs and other graphics should always have captions, unless they are "self-captioning" images or when they are unambiguous depictions of the subject of the article.

Formatting of captions

  • Captions normally start with a capital letter.
  • Most captions are not complete sentences, but merely sentence fragments that should not end with a period. If any complete sentence occurs in a caption, all sentences and any sentence fragments in that caption should end with a period.
  • The text of captions should not be specially formatted (with italics, for example), except in ways that would apply if it occurred in the main text.
  • Captions should be succinct; more information about the image can be included on its description page, or in the main text.
  • Captions for technical charts and diagrams may be substantially longer than those for other images. Captions for technical images should fully describe all the elements of the image, and the image's significance.

Bulleted and numbered lists

  • Do not use lists if a passage is read easily as plain paragraphs.
  • Use proper wikimarkup- or template-based list code (see Help:Formatting#Lists and indentation).
  • Do not leave blank lines between items in a bulleted or numbered list unless there is a reason to do so, since this causes the wiki software to interpret each item as beginning a new list.
    • Indents (such as this) are permitted if the elements are "Children" items
  • Use numbers rather than bullets only if:
    • A need to refer to the elements by number may arise; or
    • The sequence of the items is critical.
  • Use the same grammatical form for all elements in a list, and do not mix sentences and sentence fragments as elements.
    • For example, when the elements are:
      • Complete sentences, each one is formatted with sentence case (its first letter is capitalized) and a final period (full stop).
      • Sentence fragments, the list is typically introduced by a lead fragment ending with a colon.
      • Titles of works, they retain the original capitalization of the titles.
      • Other elements, they are formatted consistently in either sentence case or lower case.

Links

Wikilinks

Make links only where they are relevant and helpful in the context: Excessive use of hyperlinks can be distracting and may slow the reader down. Redundant links clutter the page and make future maintenance harder. High-value links that are worth pursuing should stand out clearly.

Linking to sections: A hash sign (#) followed by the appropriate heading will lead to a relevant part of a page. For example, [[FlightGear#History]] links to a particular section of the article FlightGear.

Initial capitalization: The wiki software does not require that wikilinks begin with an upper-case character. Only capitalize the first letter where this is naturally called for.

Linking in discussion pages: When adding a wikilink to a discussion page, it is preferable to use permalinks instead of ordinary links, since the content may have changed a lot before the next reader reads the comment. To highlight a specific edit, it might also be useful to link to a diff.

External links

Do not use external links in the body of an article. Articles can include an external links section at the end, pointing to further information outside the wiki as distinct from citing sources. The standard format is a primary heading, ==External links==, followed by a bulleted list of links. Identify the link and briefly indicate its relevance to the article: avoid linking to commercial and unrelated web sites, in essence spam. For example:

* [http://flightgear.org Official website]
* [https://sourceforge.net/p/flightgear/codetickets/ Bug tracker]

These will appear as:

Miscellaneous

Keep markup simple

The simplest markup is often the easiest to edit, the most comprehensible, and the most predictable. Markup may appear differently in different browsers. Use HTML and CSS markup sparingly; in particular, do not use the CSS float or line-height properties because they break rendering on some browsers when large fonts are used.

An HTML entity is sometimes better than the equivalent Unicode character, which may be difficult to identify in edit mode; for example, &Alpha; is understood where Α (the upper-case form of Greek α) may not be.

Use templates

Make use of existing templates whenever possible to ensure articles are styled in a uniform way. See the Templates Help page for a quick introduction to templates.

Formatting issues

Modifications in font size, blank space, and color (see Color coding, below) are an issue for the wiki site-wide style sheet, and should be reserved for special cases only.

Typically, the use of custom font styles will:

  • reduce consistency, since the text will no longer look uniform;
  • reduce usability, since it might be impossible for people with custom style sheets (for accessibility reasons, for example) to override it, and it might clash with a different skin as well as inconvenience people with color blindness (see below); and
  • cause disputes, since other editors may disagree aesthetically with the choice of style.

Outside article text, different font sizes are routinely used in navigation templates and infoboxes, tables (especially in larger ones), and some other contexts where alternatives are not available (such as table captions). Specify font sizes relatively (for example in CSS with font-size: 80%) rather than absolutely (like font-size: 8pt).

Color coding

Information should be accessible to all. Do not use color alone to mark differences in text: they may be invisible to people with color blindness. Also, black-and-white printouts, older computer displays with fewer colors, and monochrome displays (older PDAs and cell phones) cannot show such distinctions.

Choose colors that can be distinguished by the readers with the commonest form of colorblindness (red–green), such as maroon and teal; and additionally mark the differences with change of font or some other means (maroon and alternative font face, teal). Avoid low contrast between text and background colors. Viewing the page with Wickline can help with the choice of colors.

In addition to vision accessibility problems, usage of only color to encode attributes in tables instead of a separate sortable column, disables the use of the powerful wiki sortability feature on that attribute for all readers. Even for readers with unimpaired color vision, excessive background shading of table entries impedes readability and recognition of wikilinks. Background color should be used only as a supplementary visual cue, and should be subtle (consider using lighter, less-dominant pastel hues) rather than a glaring spotlight.

Invisible comments

Editors use invisible comments to communicate with each other in the body of the text of an article. These comments are visible only in the wiki source—that is, in edit source mode, not in read mode.

Invisible comments are useful for flagging an issue or leaving instructions about part of the text, where this is more convenient than raising the matter on the talk page. They should be used judiciously, because they can clutter the wiki source for other editors. Check that your invisible comment does not change the formatting, for example by introducing white space in read mode.

To leave an invisible comment, enclose the text you intend to be read only by editors between <!-- and -->. For example: <!--If you change this section title, please also change the links to it on the pages ...-->

Reference

This document contains a selection of relevant sections from Wikipedia:Manual of Style This is a link to a Wikipedia article.

Related content