×
Namespaces

Variants
Actions
Revision as of 09:29, 19 September 2012 by hamishwillee (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

FNWiki:Manual of Style

From Nokia Developer Wiki
Jump to: navigation, search

Contents

Abbreviations

Do not assume that your reader is familiar with the acronym or abbreviation you are using. Spell out the acronym or abbreviation on the first reference and then show the acronym or abbreviation after it, in parentheses. For example: integrated development environment (IDE).

Avoid using abbreviations such as i.e. and e.g.


Acronyms can have more than one meaning for instance. For example, IDE is an acronym for: Integrated Development Environment, Integrated Drive Electronics, Interactive Design and Engineering, Interface Design Enhancement.

American/British English

British English is preferred (Nokia Developer convention).

Capitalization in headings

Capitalize only the first word of the heading and proper names.


Captions

All figures, tables, and photos should be captioned. Long code examples can also be captioned, in which case Example should be used as the label. Never let captions extend beyond one paragraph in length (and note that one-line captions are the ideal). Use initial capital letters only for the first word, proper names, and code in a caption. When a caption forms a complete sentence, end it with a punctuation mark (usually a period). When a caption does not form a complete sentence, do not end it with a punctuation mark.

Dates

Use the British style day month year, as in ‘1 February 2008’.

Device nomenclature

Devices should be referred to using the format: "Nokia" Model Number" "Descriptor", for example, "Nokia N8 device".

There are a number of descriptors, including smartphone, communicator, music phone, sport. You can determine the correct descriptor from the Press Releases page - if you can't work it out, the default "device" is acceptable.

File names and file name extensions

Use the code font for file names and file name extensions.

Java terminology

Use a trademark ( ™ ) with the first reference to Java. Like all trademarks, Java is not to be used independently — that is, never as a noun and never hyphenated with another word (thus Java-enabled is not acceptable). It always modifies something. Typical references include: Java application, Java platform, Java technology. Do not use Java 2 Platform, Micro Edition (J2ME). Instead, use Java Platfrom, Micro Edition (Java ME).


Lists

Capitalize the first word of every item in a list (unless it’s a lowercased proper noun, such as elkware). End each item with a punctuation mark (usually a period). Use bullets in unordered lists and numbers in ordered lists, such as step sequences.


Person, voice (active/passive)

Use third person in content aimed at a variety of audiences (for example, introductory material for both programmers and marketers). Use second person sparingly, and only in content aimed at a particular audience (that is, where you is unambiguous), and especially in instructional material. Most writing calls for the active voice. It’s clear, direct, and takes fewer words than the passive. Exceptions include scientific, medical, or formal writing where using the passive voice is appropriate and may even work better.


Platform terminology

Do not use superscripts. Example: “S60 5th Edition” (not “S60 5th Edition”). In body text, do not capitalize platform in any reference to the Series 40 platform, S60 platform, or Series 80 platform.

Examples of Series 40 platform naming conventions:

  • the Series 40 platform
  • Series 40 2nd Edition
  • Series 40 3rd Edition, Feature Pack 1

Examples of S60 platform naming conventions:

  • the S60 platform
  • S60 2nd Edition
  • S60 3rd Edition
  • S60 2nd Edition, Feature Pack 1
  • the Nokia Web Browser for S60
  • the S60 emulator
  • S60 smartphone
  • S60 licensee

Punctuation

  • serial comma: Use serial comma as in coffee, milk, and sugar.
  • em dash: Use the special em dash character ( — ) to set off elements within a sentence.
  • en dash: The special en dash character (–) is used mainly for ranges.
  • hyphens, hyphenation
  • period
  • colon: Capitalize the first letter of the first word after a colon when that word begins a full sentence.
  • semicolon
  • quotation marks: Use single quotation marks in preference (British style)
  • exclamation mark: Use sparingly, if at all

Use a single space after punctuation (period, question mark, etc.) at the end of a sentence.

References and links

In a reference to a book, use this convention: Title. Last, First name of author. Publisher, ISBN: number.

In a reference to a document or an example, write the name of the reference correctly and in full, but do not use the version number.

Use the following format in the References chapter (note that underlining represents hyperlinks):

  1. Document A, available at nokia.developer.com
  2. Document B, available at www.anotherwebsite.yyy

List the references in alphabetical order. Use direct links for the documents if possible.

In text, use the following format: ... see Document A [1]. (For a Nokia Developer document, use the link to the document’s download page when possible. Also, note the hyperlinking of the document title.) ...see Document B [2]. (Don’t use a hyperlink unless you know that the link won’t break.) ... see Book Title [3].

Plan linking carefully and make sure that your links work. If you link to a Nokia Developer resource, point the link to the so-called info page of the resource (URL starts with http://www.nokia.developer.com/info/...)

SDK names

Use a capital E in the word Edition when used as part of the name of an SDK.

Symbian terminology

Use v followed immediately by the version number, as in Symbian OS v7.0s.

Topic management

Sub-headings help readers get an overview of the article and find subtopics of interest. Create sub-headings if a section becomes too long, and choose appropriate sub-headings to aid in your exposition. If at all possible, try not to change section headings and sub-headings often. Other articles may link to a specific section. It will break the section links. If you refer to a section without linking, italicize the section name. For example, this paragraph is in the section on Section management. If you link to a section, do not italicize the section name

Topic titles

  • Avoid special characters in headings, such as an ampersand (&), a plus sign (+), curly braces ({}), or square braces ([]). In place of the ampersand, use the word and unless the ampersand is part of a formal name.
  • Avoid putting links in headings; try to link the first occurrence of that word in the section text, instead.
  • Keep the heading short: headings with more than ten words may defeat their purpose.
  • Avoid redundancy and unnecessary words in headings, such as articles (a, an, and the), pronouns, and repetition of the article title.
  • Do not give identical titles to different sections. Doing so would tend to confuse the reader, and would make it more difficult for any writer to create a section link to any such section except the first.

Online writing guidelines

  • Keep topics short.
  • Write in minimalist, Web-authoring style. Avoid extra words which provide no actual information, such as “however”, “therefore”, and “In this topic...”
  • Break the content in each topic into scannable and digestible chunks. Break content into blocks with block headings. Write only one idea per paragraph. Keep paragraphs short (max. 6 rows).
  • Present the main idea first. Never place important information at the end of the topic because the user might not scroll down that far.
  • Plan linking carefully and check that links work.
  • Write consistently.

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, that is, font-size: 80%; not an absolute size, for example, font-size: 8pt. It is also almost never a good idea to use other style changes, such as font family or color. Typically, the usage of custom font styles will reduce consistency — the text will no longer look uniform with typical text; reduce usability — it will likely be impossible for people with custom stylesheets (for accessibility reasons, for example) to override it, and it might clash with a different skin as well as bother people with color blindness; and increase arguments — there is the possibility of other Wikipedians disagreeing with choice of font style and starting a debate about it for aesthetic purposes. For such reasons, it is typically not good practice to apply inline CSS for font attributes in articles.

Markup

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.