User:Bbbbbbbbba/Proposal of manual of style

From Glitch City Wiki
Jump to navigation Jump to search

This page describes the preferred conventions of writing at Glitch City Wiki.

These rules are not considered mandatory constraints for new content, so if you want to add something to the wiki and do not have time to read this page through, do not let the worry that you may break a rule here stop you from contributing. On the other hand, if you want to write in a style that does not look like some other page on this wiki, but is consistent with this style guide, then you can rest assured that the other page is wrong.

In fact, these rules are better thought of as guidelines on when it is acceptable to make style changes on existing pages. In general, you should not make style changes on existing pages without good reasons, but the existing page not conforming to these rules is a good reason. Consistency may also be a good reason, but if you are adding new content to a page, try to make your content consistent with the existing style, not vice versa.

Golden rule: accessibility

The ultimate goal of any manual of style is to improve the accessibility of the text, i.e., to make it easier to read and understand, and also make it easier to use otherwise (like when searching). In general, when all text on a website follow the same style, people will know what to expect, and their cognitive load would be reduced.

However, there may be special cases where following the usual style would impede readability even more. If you are sure that you have encountered one of those cases, feel free to deviate from these rules. (In some cases you may want to add an invisible comment to show other editors your thoughts.) Conversely, when making style changes to conform to these rules, please also put in some thought to make sure that you are not sacrificing readability.

Also, in many cases, different people would find the most accessible way to present something to be different. For example, a person who grew up in the US may find it jarring to use single quotes as outer quotation marks, but another person who grew up in the UK may find it equally jarring to use double quotes as outer quotation marks. As another example, casual players may find technical phrases obtuse and difficult to parse, but technically-minded glitch researchers may find them clearer and more concise than everyday speech. Therefore, this document reflects our attempt to balance between different reader demographics, which is of course not perfect. If you believe one of the rules in this document could use some improvement, please discuss with us through the GCRI Discord or on Glitch City Wiki talk:Manual of style.

General rules

Since Glitch City Wiki is a small wiki, we prefer not to make our rules up from scratch, but to follow the examples of other successful wikis. Therefore:

The rest of this page will mostly be rules specifically on writing about glitches, including their procedures, results, and explanations. However, there may also be cases where we explicitly override guidelines from one of the above documents, and obviously this page takes precedence. Conversely, we may also repeat some of those guidelines in this page if we believe they are especially relevant to this wiki and more important to follow.

Introduction

See: Wikipedia:Manual of Style/Lead section

The introduction should serve to give an overview of the subject of the article.

  • Generally, the introduction should begin by briefly defining the term or glitch being discussed, which is named in boldface. Any alternative names of the subject, or related terms defined in the same article, should also be named in boldface. (Those names should usually be redirected to the page in question.) For related terms defined in a different article, obviously a link should be used.
  • Avoid spending a sentence stating that "[Subject of the article] is a glitch (in certain versions of the game)." The extension of the term "glitch" is so broad that this is not an interesting statement. Instead, try to define the glitch and show its significance, usually either by summarizing what it does, or by noting its most remarkable consequences.
  • Conversely, also avoid diving immediately into technical details in the first sentence. If what a glitch does exactly is too hard to summarize, then consider the "noting its most remarkable consequences" approach.

Third person point of view

Similar to on Wikipedia, first-person and second-person pronouns should generally be avoided.

  • The author's we is acceptable and is the most common exception to the above rule.
  • Meanwhile, the editorial we is generally not acceptable, especially since it usually reflect a violation of the neutral point of view policy (but see below about policy documents).
  • When referring to the person who is assumed to be performing a glitch (or some other procedure), use "the player" instead of "you". To refer to the player again, use the singular they, or just spell out "the player" again (when the singular they may be awkward). Alternatively, rephrase the sentence to eliminate the need to explicitly refer to the player, which is often possible, such as in the following example.
    • Incorrect: You must use a Pokémon with a Special of 21 to get a Mew.
    • Correct: Using a Pokémon with a Special stat of 21 results in a Mew.
  • Complicated procedures are often described as a numbered list or bulleted list (usually the former, unless the procedure is very long, such as a speedrun route) of steps, and for each step an imperative sentence should be used. This creates a mild implicit reference to "you", but is considered preferable to the verbosity of stating "The player should ..." for each step. However, explicit references to the player should still be worded as "the player".
    • Example:
    1. Walk a step up.
    2. Immediately after the step has finished, press Start. The player can "buffer" this button press by pressing and holding Start while still in the middle of the step.
  • In policy documents, such as this page, this rule does not apply, meaning that you can use the editorial we to refer to the Glitch City Wiki community as a whole, and "you" (instead of "the editor") to refer to the reader that is assumed to be editing a page. This is to avoid distancing the readers and to remind them that every new user of this wiki is also a potential editor.

Quotations

See: Wikipedia:Manual of Style#Quotations

Use double quotes as the outermost quotation marks, which is the dominant usage pattern in American English, but also has some acceptance in British English. However, when it comes to the order of punctuation around quotation marks, follow the so-called "British practice", which is also known as "logical quotation". This means that do not put punctuation marks inside quotation marks unless they actually belong there:

  • Incorrect: During the old man's catching demonstration, the player's name is temporarily changed to "OLD MAN."
  • Correct: During the old man's catching demonstration, the player's name is temporarily changed to "OLD MAN".
  • Correct: When the player saves the game in Pokémon Gold, Silver and Crystal, the game prints "SAVING… DON'T TURN OFF THE POWER."

Regardless of logicalness, avoid using two end marks (?, !, or .) both inside and outside the quotation marks:

Ambiguities may arise if the quoted text ends with an end mark, but not to end a sentence. Such ambiguities can be avoided by adding a parenthesized remark:

  • Problematic: Name the player character "♀:MNa.".
    • Even if we use end marks both inside and outside the quotation marks, it can look like a typo.
  • Better: Name the player character "♀:MNa." (ending with a period).

Links

See: Wikipedia:Manual of Style#Links
  • Since we are not as comprehensive a wiki as Wikipedia, overlinking is less of a problem. Still, only link to another page because it may help the reader understand the current article, not just because it is on our wiki.
    • The page Glitch is one that generally should not be linked to, except maybe when talking about a controversy whether a certain behavior should be regarded as a glitch. Meanwhile, pages like Glitch Pokémon, Glitch item, etc. contains technical information about the specific class of glitch objects, and usually are helpful to link to.
  • Avoid linking the same term twice in short succession. However, when a term's occurrences are far from each other, it may be likely that the reader would see a later occurrence without noticing the first one. In such cases, link the same term as many times as necessary.
    • In general, for concepts that are highly relevant to the subject of an article, the reader should expect to find a link in the introduction, so there is no need to link to them a second time. For example, in Toxic accuracy bypass glitch, the terms "Poison-type" and "Toxic" only need to be linked once.
  • Use interwiki links to Bulbapedia for Pokémon terms that are not glitch-related, such as specific Pokémon types, moves, and Abilities.
    • Such links should only be used when the non-glitch-related properties of the object in question is relevant. For example, in Celebi Egg glitch, do not link "Celebi" because it is a largely arbitrary example of a Pokémon to obtain, and definitely do not link "Beat Up" because it is only relevant since it shares an internal ID with Celebi.
    • General concepts, like "move" and "Ability" themselves, usually do not need a link.
    • Use the pipe trick to decrease the chance of a typo: [[bp:Substitute|]] will be automatically expanded to [[bp:Substitute|Substitute]]. Note that this means that when you edit the page again, you will see the latter form even if the previous editor entered the first form.
    • Remember to check if the target is a disambiguation page. [[bp:Thunder|]] would link to the disambiguation page Thunder, but [[bp:Thunder (move)|]] will render correctly as Thunder.
    • In most cases, do not link to Bulbapedia's glitch-related pages in the body of an article, since we are supposed to do those pages better. Instead, on a page with an equivalent page on Bulbapedia, use the template {{bulbapedia}} or {{bulbapedia2}} to link to the latter.
  • Similarly, use interwiki links to Wikipedia for non-Pokémon terms that may be helpful to link to. The prefix is wikipedia:.
  • Similar to on Wikipedia, external links should not usually appear in the body of an article. They belong to the references or a separate section.

Pokémon franchise terminology

When writing about Pokémon, conventions at Bulbapedia should generally be followed. Refer to Bulbapedia:Manual of style#Pokémon franchise terminology for a summary of those conventions.

Capitalization

Apart from following the capitalization conventions at Bulbapedia:

  • Names of D-pad buttons, such as the up button, are not capitalized, but names of other buttons, such as the A button or the Start button, should be capitalized as shown here (capitalize the name, but not "button"). This extends to terms such as "the Start menu" and "the Select glitch".
  • Names of glitches are usually not considered proper names, and so are not capitalized unless the first word should be capitalized for other reasons.

Technical language

Special characters

Some glitch procedures involve strings that can be input by the player (usually names): the name of the player character, the rival, a Pokémon, a box, etc. Depending on the game, the player will be able to use various special characters in the string. Those special characters must be conveyed in a clear and unambiguous way.

  • If a special character can be represented with a single standard Unicode character, do so. Examples include é, ♀, × (the multiplication sign), etc.
  • If a special character can only be represented or described with multiple standard Unicode characters, then there will usually be a template for it, such as {{PK}} (PK) or {{MN}} (MN). (Combinations of the apostrophe and a letter are an exception; see below.)
    • In case such a template does not exist, or you cannot find it, you can also enclose those Unicode characters with angle brackets, like <PK> or <MN>.
    • As a special case, if the apostrophe is not in the available character set, but combinations like <'s>, <'t>, etc. is, then the angle brackets can be omitted. However, consider using spaces to separate the characters (see below).
    • In the rare case where the less-than and greater-than signs are in the available character set, always use a parenthesized remark to clarify, no matter whether they are used literally or as angle brackets to represent another special characters.
  • Sometimes it is clearer to use spaces as a separator for the characters. If so, put a space between every two characters in the string. In case a literal space is also in the string, represent it with <Space>.

Hexadecimal numbers

  • Hexadecimal numbers should use upper case letters A–F, rather than lower case letters a–f. This helps to distinguish them from Game Boy register names (see below).
  • In most cases, use the prefix "0x" for all hexadecimal numbers, even when they contain a letter (and thus cannot be confused with a decimal number) in order to keep the style consistent. There are two exceptions:
    • Memory addresses should use the prefix "$", both for unbanked and banked addresses (e.g. $DA47, $03:5142). Memory offsets should still use "0x" (e.g. ItemUsePtrTable + 0xD2).
    • When using hexadecimal values to represent a byte sequence (instead of any big-endian or little-endian number the byte sequence may represent), use spaces to separate the bytes (e.g. "10 24 00 08"). There is no need to add any prefix even when the hexadecimal representation does not contain a letter, because it should be understood that a two-digit decimal number cannot represent a byte.

Assembly

Terminology and Nomenclature