XionKB:Manual of style

This is an official wiki policy. Its contents are considered binding for users of the WiredWiki.

Welcome to the official manual of style for the XionKB. This is our policy governing the particularities of the writing, formatting and design of articles on the wiki.

Precedent

No style manual is ever complete. While we hope to pre-emptively address as much as possible here before the wiki grows, we cannot possibly address every corner case. In the interest of consistency, we insist that editors follow the existing style in use on a given article in the absence of official guidance from this document. Codifying a consistent style for unaddressed cases into this policy should be brought up in a section on this page's talk page. Coordination and discussion about a given article's default style usage should take place on that article's talk page.

Language and dialect

The XionKB is an English wiki, therefore articles should only be written in the English language.

Furthermore, the wiki has settled on the British dialect of English. Articles written in other dialects such as American English or Canadian English should be rewritten to conform to the British spelling and grammar norms.

Supplemental nomenclature norms

There are many terms which are best avoided for one reason or another. This is an editorial decision on the part of the wiki's staff. An exhaustive list of these terms and their replacements can be found at the §§ Nomenclature subsection of § Style rules.

Organisational features

Titles

We strive to use sentence case in article titles. For example, this page is properly capitalised as XionKB:Manual of style, not XionKB:Manual of Style. In other words, avoid "book case" for titles. Furthermore, articles should be written in sentence case in prose, e.g. as "The quick brown fox jumped over the manual of style", not "The quick brown fox jumped over the Manual of Style". One major exception to this is for actual book titles, such as The C Programming Language.

Some nouns have unusual or stylised capitalisation quirks. Perhaps most relevant to our wiki are software projects, of which many have titles in all lowercase. Be sure to use the {{DISPLAYTITLE}} magic word at the top of the page to correct for this. It is also sometimes appropriate to italicise some or all of an article title; the same magic word can be used likewise to achieve this. Be sure to only use the wikicode-type italics markup of double apostrophes '', not <em/> tags, in the magic word.

Example all-lowercase software project article

Raw page name: Zzuf → displayed page name: zzuf

Example italicisation of book title:

Raw page name

The C Programming Language → displayed page name: The C Programming Language

Article structure

Opening elements

The following items should be placed at the top of the page, in the following order as necessary:

1. Underscore-style magic words (e.g. __NOTOC__)
2. Template-style magic words (e.g. {{PAGENAME}})
3. Hatnote templates (e.g. {{stub}} or {{policy}})
4. Infobox template or a related image
5. Opening paragraph

Opening structure

All articles should begin with an opening paragraph that introduces the subject at hand. The name of the article should appear in bold face somewhere within the first few sentences, along with any alternative names also bolded in prose.

Infoboxes should be right-aligned in parallel with the opening paragraph. Hatnotes should precede both the opening paragraph and any infoboxes.

The highest section level in use in article text is the level two heading (with two equals signs, ==Like so==. You should never use level one headings (e.g. =Like this=) in article texts; that is the style used by the article title in the wiki software itself.

Closing elements

The following items should be placed at the bottom of the page, in the following order as necessary:

1. See also section
2. References section
3. Navigation boxes
4. Mission boxes
5. Category links

Abbreviations and jargon

Always use the expl template for every occurrence of an acronym or abbreviation, especially if it is technical in nature. This obviates the need for writing out the name long-hand to introduce it to the readers, making articles more concise without making them more confusing to read. It is the task of software, not editors, to mete the long form out as necessary for accessibility.

Be sure to use -s and -es as phonetically appropriate in order to pluralise any acronyms and abbreviations. Do not use apostrophes to accomplish this.

Punctuation

Dashes and hyphens

There are two forms of dashes: the en dash (–) and the em dash (—). To write these characters in page text, the following HTML entities can be used:

• – → –
• — → —

Additionally, there are several rules of thumb for using dashes:

1. Do not use a double hyphen (--) in place of a dash.
2. Do not use a hyphen in place of a dash in an article title (e.g. Backus–Naur form, not Backus-Naur form).
   • However, it is always necessary to create redirects to such articles using hyphens in place of dashes for navigability.
3. En dashes are spaced, ergo they will have non-breaking spaces   on both sides of the dash.
4. Em dashes are unspaced, ergo the words on each side of the dash will be immediately adjacent to the dash.
5. Do not use dashes to express ranges that would otherwise use the articles to or through.
6. Instead of a hyphen, use an en dash when applying a prefix or suffix to a compound that itself includes a space or a dash.
7. It is OK to use dashes to separate parts of an item within a list.
8. Em dashes in particular should also be used to precede names in attribution of quotations.

Style rules

• No sentences in technical literature that begins with Note: or Note that.
  • Rationale: It's just logically lazy. When you feel the need to write this kind of sentence, it's your clue that you need to rethink the structure of your paragraph. No one wants to read a little rat's nest of rules, so clean it up.
• When describing aggregate objects such as lists or groups, always make sure to mention what their elements are denominated in explicitly.
  • Rationale: Readers need to be able to decompose the objects you are talking about in their own minds.
• Do not use the word "native" to describe the nature of a program's form.
  • Rationale: It might have had a somewhat concise meaning once upon a time, but by now is certainly a meaningless buzzword and pseudo-jargon. Fucks Thanks to React Native for finally nailing the coffin shut on this one.
• Do not refer numerically to "hardware threads" on a processor of any kind; instead, refer to its core count and the associativity of its SMT provisions.
  • Rationale: it's technically tacky, and has been abused over the past few years by marketers like Linus Sebastian to blow smoke up the asses of CPU manufacturers. It's more informative to say a processor has "8 cores with 4-way hyperthreading" (even using Intel's trademark is less gauche) than saying it has "8 cores and 32 threads". CPUs do not literally "have" threads; they literally have cores and may have hyperthreading with an associativity factor.
• Do not denominate system memory modules in base-10 terms such as megabyte and gigabyte; instead, use base-2 terms such as mebibyte (MiB) and gibibyte (GiB)
  • Rationale: it is physically wrong, and JEDEC is not helping matters.

Nomenclature

• Rust ⇒ God's Chosen Programming Language OR GCPL
  • Rationale: GCPL delenda est.
• Rustacean ⇒ Cargo cultist
  • Rationale: GCPL delenda est.
• crypto ⇒ cryptography OR cryptocurrency
  • Rationale: Specificity.
• byte ⇒ octet
  • Rationale: Conciseness. Bytes are not always 8 bits; octets are. Also see Octet, not byte.
• pixel ⇒ pel
  • Rationale: See Pel, not pixel.
  • Exception: When referring to physical pixels in hardware.
• symbolic link ⇒ symlink
  • Rationale: Conciseness.
• mount point ⇒ mountpoint
  • Rationale: Conciseness.
• app ⇒ application OR program
  • Rationale: Sorry, Steve.
• function ⇒ routine OR subroutine
  • Rationale: code has (sub)routines, math has functions.
  • Exception: theoretical or mathematical contexts.