Scratch Wiki:Editing Conventions

The Editing Conventions is a reference article used to summarize points all pages on the Scratch Wiki should conform to.

This does not relate to pages in the userspace.

Writing/Content

Article titles

Article titles should follow American spelling conventions. See #Standard English for more information.

Topic

Article titles should be chosen such that:

  • The article title is short and concise.
  • All content in the article should be related to the title.
  • There is no markup in the title, such as adding italics to a title.
  • There are no links in the title, both internal and external links.
  • The article title doesn't start with an article (a, an, the) or a preposition unless it is a direct quote/name in which case an article or a preposition must be present.
  • The title doesn't have punctuation marks/symbols, unless it is a direct name (for example, Set Video Transparency to ()% (block)) or if it is part of the FAQs.
  • Use brackets after the title to clarify what the title refers to, such as the difference between Curator (front page) and Curator (studio). Also use brackets for important Scratch Wiki maintenance pages (such as Disambiguations).
  • A replaced character (because of title restrictions, see () is less than () (block)) is replaced with common, non-colloquial alternative text (no numbers), to facilitate readability.
  • There are no extraneous details. For example, instead of "Scratch", one puts "Awesome Scratch".

Any content on the article that does not relate in anyway to the title should be taken out, or the title should be changed to encompass the ideas of the whole article. This type of title change must be discussed in the Community Portal, to prevent deviation of the main idea of the article.

Capitalization

Generally, all the words in a title (including the first word) should be capitalized, but exceptions occur when:

  • The word is an article, a preposition or a coordinating conjunction (of, on, in, or, and, etc. For example, Project Information and Help).
  • Lowercase "to" in the infinitive (for example, "to Eat").
  • The page is a FAQ, in which case all of the words need not be capitalized.
  • The word is in brackets, for example, Backdrop Number (block)
  • The title relates to a Scratch block and the title has words that replace the actual word on the actual block due to title restrictions, such as () is greater than () (block), replacing the greater sign with "greater than". The extra words should not be capitalized.
  • The title relates to an element on Scratch or on the Scratch Wiki that is not capitalized (e.g. Help:New images).
  • The name of the subject of the article has a deliberately decapitalized first letter. Note that MediaWiki automatically capitalizes article titles - though this can be worked around with the magic word DISPLAYTITLE, it does not change the URL address.

Block names have no capitals, but titles relating to them must have capitals retaining to the rules above. For example, in the page Backdrop Name (block), instead of "backdrop name (block)", it must be changed to "Backdrop Name (block)".

Page body

Introductory paragraph

The first few sentences of the article should explain the title in a quick way. It should explain at least one aspect of:

  • Who the person is - what was its significance (for example, Kaj)
  • What it is - how does it relate to the wiki (for example, Recently Shared Projects)
  • Where it is - where it is on the website/program and how scratchers will find it (for example, Scripts Area)
  • When it happened/happens - when did it take place (for example, Creative Characters Camp)
  • Why it happened/happens - why did it happen (for example, Ban)

The introductory paragraph should also restate the title, which should be bolded with three apostrophes ('''title'''). Capitalization of the title should not be included in the bolded word. Instead, use regular English grammar. Some exceptions retaining to this restatement include:

  • If the title is an original name, and changing the capitalizations would change the context, keep the capitals. For example, Sound File Format changes to "sound file format", however Mix and Match Camp is a name, so capitalization in the restatement is not changed.
  • Brackets are not kept, but capitalization for blocks remain the same as the title, for example, Tempo (block) changes to "Tempo" and Project Downloading (1.4) changes to "Project Downloading".
  • For Scratch Program values, capitalization in the bolded word should be based on the English grammar rules.

Do not start the first sentence of the article with a adjective, verb, or preposition, unless it is in the restatement.

Wikilinks

Wikilinks, or internal links, are links that link to one page on this Scratch Wiki. Potential wikilinks should be spotted, as wikilinks help to increase ease of use. Multiple wiki links are when a page links to another page two or more times. This is generally disallowed, with a few exceptions.

  • If a link appears in a template, such as {{note}} or {{navbox}}, one more is permitted in the article.
  • If a link appears in an image, one more is permitted in the article.
  • If a link appears in the "See Also" section header, one more is permitted in the article.
  • If one appears as a list element (as in Front Page#Rows), one more is permitted in the article.

Headers

Wiki headers follow the rules of a article title, and be concise and to the point. However, header names do not need to have capitals of every word. Only use headers when there is a change of time, or subject. For example, in Sound Blocks, it starts with a introductory paragraph, then the subject changes to all the blocks in the Sound Block category. Then, the subject changes again to "Scratch 2.0 Sounds". The header's contents must describe the header fully, and it should not be a filler, such as "no content here", or "there is nothing here yet". There are six levels of headers, ranging from big headers of level 1 to small, level 6 headers. The Scratch Wiki Cheatsheet provides examples of these headers. In articles, we can "nest" headers, which means we can place headers into another header's content. One nests headers when a subject/time change is present in an already existing header content. However, under no condition should the level one header be used. This header is reserved for the page title.

  • Headers should contain English text and numbers only. There should not be any punctuation, unless a direct name is used.
  • Headers should not include links of any sort, including internal and external links. Use {{main}} to avoid doing this.
  • Header structure should be organized - smaller headers are always nested in bigger headers. (see Help:Tables for a nicely organized page).
  • Headers should be used sparingly so as not to confuse readers and editors.
  • Standard English rules apply to the header.
Header Beginnings

For every header, refer to the same rules in #Introductory paragraph, without bolding the restatement.

See Also, External Links, References

The section headers "See Also", "External Links" and "References" should have each word capitalized, and appear exactly like the examples here. The location of these header should be at the very bottom of the page, and from top to bottom, the "See Also", then "External Links", then "References" header.

Currently

Do not use "currently" in wiki formal writing. Instead, use "as of (a date)".

Referencing other objects on the page

When referring to a table, you may say something like "...the table, shown above" or some variation of it. This is discouraged as wiki content is dynamic, and will change locations. Saying "to the left", "to the right" or directions to words/images in the same page should not be done. Instead, use image captions, table captions, or anything avoiding directions to objects on the same page.

Standard English

Variances in English

English can have different dialects, and different ways of saying similar things. For example, a pickle in American English is a gherkin in British English. In general, the most used English word around the world should be used in the Scratch Wiki. Do not assume that any word from American English can be used. For example, "eyeglasses" (American English) should not be used. Instead, use "glasses". This rule does not apply to cases where a subject/article originates from a different type of English.

The style of English is set when the article is created. If an article is created with the word "colour", then it should be retained as such.

Article titles should follow American spelling conventions to follow block names.

Scratch Wiki is a professional encyclopedia, so as such, avoid jargon and everyday language at all times. Instead of saying "Wow, Scratch 2.0 came out in 2013.", say "Scratch 2.0 was officially released on May 9, 2013." Writing should address everyone, from different genders to different races. This includes writing an article where everyone, experienced and not, can read it.

Official names

Official names, or direct names, are names of things in which the format breaks the normal Wikipedia English conventions. For example, Mouse Down? (block) breaks the convention, as it has a punctuation mark in the title. However, in the case of an official name, it must be retained in the article. Thus, doubling punctuation is OK, if your case is not listed below. This rule is no longer valid if there are technical/readability restrictions, such as:

  • Title character restrictions, in which case see #Topic.
  • Character confusion (such as using "Mouse Down?" in a question, creating double-punctuation, in which case change the sentence structure to avoid it. Periods, question marks and exclamation marks do not pair up.[1])
Pronouns

Professional encyclopedias should always be unbiased, and that means any personal tenses (first-person) are not allowed. Use only if it is in a direct name, or in quotations. Also, avoid our, us, we, or any contraction with it (for example, let's).

In informational articles, avoid "you" or any second person pronouns at all costs. General ways of accomplishing this include (the sentence that requires fixup is "You must click the green flag to...):

  • Using an impersonal subject: "Scratchers must click the green flag to..." or "One must click the green flag to..."
  • Using passive voice: "The green flag must be clicked to..."
  • Using the imperative: "Click the green flag to..."

In tutorials, use "you" only when giving instructions to the user. For other content within a tutorial article (such as explaining a concept but not giving direct instructions on how to apply it), follow the rule above and avoid using "you".

In FAQ articles, only use "you" inside the FAQ box - in extra content, refrain from using "you".

Parentheses and brackets

Punctuation ending a sentence should placed out of the parenthesis if the text inside the parenthesis forms a phrase. Punctuation should be inside the parenthesis if the text inside the parenthesis forms a complete sentence. For example, one would write "The bear ate the berry (it was a big one!)" or "The bear ate the berry (quickly)!". Brackets should be placed inside quotes when a short sentence/phrase/word is needed to be added in order to increase the understandability of the quote. For example, if a quote says "incorrect may be detrimental", someone may add "incorrect [Scratch] may be detrimental", as now understandability is increased for other readers. Do not add adjacent bracket/parenthesis pairs. In all cases, parentheses and brackets should not be added to the body content if:

  • It relates to an opinion.
    • Emphasis of a point.
Contractions

The use of contractions (for example, "don't" instead of "do not") should be avoided. However, sometimes expanding the contraction results in awkward phrasing and grammar. In that case, edit the whole sentence to achieve the same purpose as before.

Quotes

To quote someone is to copy word for word what they have said/written, and give them credits for it. One must use either {{quote}} or {{quote2}} to quote someone. The quote must not be edited, and must be referenced to the original quote. If it isn't referenced, add {{Fact|quote}} after the quote. The following exceptions apply:

  • If there is a string of quotes, the previous sentence which is not a quote can be referenced to the general location where all the list of quotes came from (see ITopic:Welcome to Your Local Block Library!).
  • If the quote has a spelling error, one may add "[sic]" after the misspelled word, as long as there are not too many instances of it. See Wikipedia:Sic for more information.
  • If the name is not known, mention that before the quote starts. However, the usage of {{quote}} or {{quote2}} is still in effect.
  • If the reference is not online, use the MLA formatting to cite where your reference is.
  • If the quote has minor importance in the article (eg. can be removed from the article without major issues), it may be added in line with text. However, it must be referenced. Adding the name of the person who said the quote isn't required, as long as the reference clearly states the author.

Topic examples

Sometimes, examples are used to allow readers to experience the topic the page is representing. For example, Game Projects#Examples. Examples are a key resource to use, however, there are rules on when to use them and how:

  • There should not be a list of examples for anything not directly and only related to Scratch. For example, Scratch Memes are directly related to Scratch, however, pixels are not.
  • Examples should not indirectly refer to something. For example, if there was a page talking about Scratch bugs, a project talking about bugs is not appropriate.
  • There should be a maximum of three examples per topic explained for bullet lists, and a maximum of 7 for tables. The examples must be listed under a header two, or three header. No other header is accepted for examples.

Images

Images uploaded on the wiki can be placed in any page, so long as it relates to any topics from any header. Images are used to clarify a point or add to a point. Images should also be added for important points to help visual learners.

Topic

Images should be picked such that:

  • The image shown is the main subject in the image. There should be no question in which subject is being shown. Factors that determine the main subject include size, color, camera angle, and other prominent features.
    • Two subjects in an image should be avoided. A picture of a television with a image of a computer should be avoided. Instead, the image should be a television turned off. Similarly, an uncropped photo of a browser showing the Scratch website should not be uploaded.
    • If an image of the page title is used, it should be the first image that appears from top to bottom.
      • The main image shows the unmodified object. Variances of the main image should not be included as the first image, however, it can be added as additional images for the article.
      • The main image is the first image the viewer sees, so it must be an accurate representation. Thus, it should have the best quality.
  • Images that relate to the same topic on the same page should have variety, such as a different format (image, video, etc.), different style (Scratch Cat in Scratch 1.4 compared to Scratch 2.0), or anything that is not redundant.
  • The image is on topic. Images can be picked to represent important information from any header section. For example, a picture of a page topic, and a picture of it 2 years ago is acceptable, provided that the two images have variances. Generally, images should be made to represent information worthy of being in a new section header.
  • The image picked is not inappropriate. Inappropriate images include vulgar, offensive and otherwise mean images. If one sees a mildly inappropriate image, assume good faith. Otherwise, revert immediately, and tell an administrator or an Experienced Wikian listed here.

Size, location, format

The size, location and format are also important, as it relates to what topic/header the image is referring to.

  • For frame/thumb images (see Help:Images) that cut into other headers, the actual image must be in the header that it refers to. If the image goes into other headers the image that it relates to is unclear, and is not allowed.
  • Images that are in the introductory paragraph should always be aligned to the right.
  • Generally, no image should be inline with text.
  • Is it recommended that the "alt" property of images be filled out.
  • The horizontal size of the image should not exceed half of the page's available space (less than 350px) and the height should not exceed 700px.
  • All images should be compressed, if it exceeds 500KB.
  • Keep in mind that all images will be made into a rectangle.
  • The image size of the picture should be dependant on the image subject. An image with lots of detail (for example, File:3D Game.png) can be bigger in the article. On the contrary, an image with little detail (e.g. File:Netpbm Example3.png) should be smaller than usual.

Templates

Most important templates should be put first onto the page so that it is seen first. Usually, these templates provide a negative connotation. {{Delete}}, {{Not Useful}}, {{Bad Image}} and {{Wiki Standards}} should always be put first on the page. Identification should also be on top of the page, for example, {{Block}}, {{Bot user}}. {{Disambig}}.

References

  1. http://www.subversivecopyeditor.com/blog/2010/08/double-punctuation.html
  • This page was last modified on 1 December 2017, at 13:25.