Help:Contributing

Revision as of 09:22, 1 June 2015 by Mark Otaris (Talk | contribs) (Disambiguation rules: move the disambiguation rules to help:disambiguation)

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

This help page is a guide meant to help writers and editors understand the particularities of this wiki. In particular, it indicates which templates are the best to use when writing articles. This guide assumes that you know wiki markup. If you do not, the first thing you should do is read through MediaWiki's help section. The guidelines given in Wikipedia's manual of style, which are more detailed and cover more subjects than this page, should generally be followed when writing articles on this wiki.

API documentation

The scripting API provided by ROBLOX is documented in the API namespace using the APIClassPage and APIMemberPage templates. The former is used for documenting classes, while the latter is used for documenting members (properties, events, methods and callbacks).

Classes should be described on subpages of the page API:Class (e.g. API:Class/Instance). Members should be described on subpages of their class' page. The pages in the main namespace with the name of classes or members should redirect to the page of these classes and members in the API namespace.

Enums are documented using the APIEnumPage template. Enum items do not have a specific page, and all descriptions of enum items should be included on the page of the enum they belong to. All enum pages should be subpages of the page API:Enum, in the same way that class pages are subpages of API:Class.

Disambiguation rules

Main page: Help:Disambiguation

In order to make linking to pages in the main namespace as natural as possible, to avoid breaking existing links and to make search results more relevant, the following rules should be followed for pages in the main namespace with a name that is shared (or not) by many articles:

  • If there is only one article, the page should redirect to that article.
  • If there are many articles...
    • If none of the articles is an API documentation page, the page should be a disambiguation page providing a list of the articles.
    • If many of the articles are API documentation pages, the page should be a disambiguation page providing a list of the articles.
      • This can be automated with the {{member disambig}} template
      • However, if one of the API pages concerned is about a member or a class that is significantly more common than the others, the page should redirect to that page instead.
    • If (only) one of the articles is an API documentation page, the page should redirect to that page.
  • In all cases, if the page redirects to an article and there are other articles that share the name of the page, these other articles should be referred from the article that the page redirects to with the {{redirect}} template.
    • If there are more than three other articles, the {{redirect}} template should be used to link to a page in the main namespace with the name that is common to the articles but suffixed with " (disambiguation)". That page should be a disambiguation page providing a list of the articles, including the article to which the page redirects.
  • When intentionally linking to a disambiguation page, a redirect should be created at the page suffixed with " (disambiguation)", and that page linked to.

Article titles and section headings

Main article: w:Wikipedia:Manual of Style#Article titles, headings, and sections

Article titles should always start with a capital letter (the MediaWiki software imposes this). However, the rest of the words should not be capitalized unless they are usually capitalized in a normal sentence. This also applies to section headings. The capitalization in the title and in the section headings of articles that do not follow this guideline should be corrected, but there is no emergency to correct them, so this can be done case-by-case when they are noticed.

Some of the guidelines that should be followed in article titles and section headings are described below. The Wikipedia guideline referred to above is more detailed.

Article titles

  • Titles should usually be in singular rather than plural (e.g. variable rather than variables).
  • Titles should generally be nominal phrases and should almost never be questions or end with punctuation.
    • In particular, titles of the form "How to ..." (e.g. How to construct a windmill) should be avoided, and if there is no way to rewrite them as nominal phrases (e.g. Construction of a windmill), they should be reformulated as a verb phrase using the gerund of the verb that comes after "How to" (e.g. Constructing a windmill).
    • Example: The article about terrain should be named "Terrain" rather than "The terrain" or "Terrain tutorial". "Usage of terrain" is better than "Using terrain", which is better than "How to use terrain". (Note: The article about terrain is in fact named Terrain tutorial, because the page Terrain must redirect to the API documentation page about terrain, but this is an exception.)

Section headings

  • Links should be avoided in section headings, particularly if they only apply to part of it.
  • Section headings should not refer to the subject of the article (or of headings of a higher level) where doing so is redundant.
  • Images should be avoided in section headings.
  • The recommendations given in the previous section for article titles also generally apply to section headings.

Red links

Links that point to inexistent pages (red links) should not be removed solely for that reason. Wikipedia provides more recommendations about this.

Code

Lua code should always be presented either inline (inside of a paragraph) or in its own block (in the flow of the text). In the first case, the {{`}} template should be used. In the second case, the {{code and output}} template, the {{code}} template or the {{lua}} template should be used. It is better to avoid putting code in <source>, <syntaxhighlight>, <pre> or <code> tags, because they do not support syntax highlighting, are obsolete, or do not have a sane tab width. When it is not desirable to present output with the {{code and output}} template, it should be contained in a <samp> tag, optionally contained in a <pre> tag.

Line numbers and selection buttons

When the text around a piece of code refers to one or many specific lines in that code, line numbers should be shown with the line number parameter of the {{lua}}, {{code and output}} and {{code}} templates. Furthermore, a button to select the code (to copy it) should be added to long pieces of code that it is likely readers will want to copy with the copy button parameter of these same templates. The following example shows what a code block with line numbers and a select button looks like:

Wikicode:

{{code|line numbers=true|copy button=true|=
for _ = 1, 50 do
	print("Hello World!")
end
}}

Result:

Select
  1. for _ = 1, 50 do
  2. 	print("Hello World!")
  3. end

Examples

There exists an {{example}} template for creating example boxes to use to mark up examples in articles. This template, although it is used in many articles, should be avoided, in favor of creating a section named "Example" or of simply inserting the code in the flow of the text. There are nevertheless some cases where its use is appropriate, so you must use your judgment.

Indentation

Code should always be indented. Indenting should be done with tabs, not with spaces. The {{code and output}}, {{code}} and {{lua}} templates will all change the width of tabs to 4 instead of 8. The {{code}} template also allows changing the tab width with the tabwidth parameter, but this parameter's value should not be changed from the default unless there is a good reason to change it. Alignment should be done with spaces rather than tabs, and tabs should not be used for anything else than indentation.

Completeness

When adding a new class or member page to the documentation, don't create the page just so it's there, because that's really easy to do. Anyone can do that. Be exceptional by first researching what the object does. If you're stumped, ask for help on the object's talk page.

When adding examples for members, make sure they show the full usage and make sure you actually explain what they do instead of just giving code. If a method has arguments, use them. If an event has parameters, use them. Try to come up with an example that's actually useful, instead of just printing a string to show that it works. Once again, if you're stumped, ask for help on the member's talk page.

If you plan on creating a page for an object or member without having researched it, don't bother!

Image maps

This wiki supports the usage of image maps through the ImageMap extension. An image map is a list of coordinates in a specific image, which hyperlinks areas of the image to multiple destinations (in contrast to a normal image link, in which the entire area of the image links to a single destination). For example, a map of the world may have each country hyperlinked to further information about that country. The intention of an image map is to provide an easy way of linking various parts of an image without dividing the image into separate image files.

Image maps may seem complicated to use, but you can find information about them on the extension's page.

Do not use image maps to place normal images in articles. Instead, use MediaWiki's syntax:

To include a file in a page, use a link in one of the following forms:

  • [[File:File.jpg]] to use the full version of the file
  • [[File:File.png|200px|thumb|left|alt text]] to use a 200 pixel wide rendition in a box in the left margin with 'alt text' as description
  • [[Media:File.ogg]] for directly linking to the file without displaying the file

You can also give a link to a file's page by adding a colon in front of it, like this: [[:File:File.jpg]].

Finally, you can also specify what the image links to with the link parameter and you should always define alternate text for the image with the alt parameter, for accessibility reasons.

Internal links as external links

Sometimes, you might need to use the external link markup for a link that is internal to the wiki. This is the case for some special pages and for certain actions which require passing arguments to the index.php file. You should always try to use internal links when you can, but there are some cases where you will not be able to do so. When this is required, please do it with the fullurl magic word. Also, note that you can make such links look like normal internal links using the built-in plainlinks CSS class. The plainlinks CSS class should only be used for links that are internal to this wiki.

Get more help

If you have a question or you want to present a concern, an issue or a suggestion, do so on the talk page of the relevant article. If no article is relevant, do so on the general discussion page. You can also talk to other wiki writers and editors (and also other game developers and ROBLOX users) in the #roblox and ##roblox channels on the freenode IRC network.

See also