Factorio:Style guide

From Official Factorio Wiki
Revision as of 14:37, 30 July 2017 by Gangsir (talk | contribs) (Create style guide)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This is the official Factorio style guide. Please follow this guide when creating or editing pages on this Wiki.

Language

  • The default language is American English, however English pages may also use European English. All pages must have an English version, and should be translated English -> Other. Use of country-specific slang must be avoided, except for localization reasons.
  • Any other language has no right to obtain a page name which collides with English.
  • No other language has the right to use a page name which means the same or something different in another language.
  • Language pages when translated should use the English name with the language code appended to the end of the name. For example, "Transport belt" when translated to German should be named "Transport belt/de". If translating the page name is necessary, put an entry for it on the language's respective translation template, something like: Template:Translation/??
  • Page names should only be capitalized at the first word, with some exceptions. Essentially, Petroleum gas, and not Petroleum Gas. This is both for readability and for the internal code of the wiki to work correctly.

Typo control

  • Please use the "Show preview" button to view your changes before saving them, to allow yourself to catch incorrect links and typos, and improper formatting. While creating multiple edits to the same page is allowed, it creates clutter on the recent changes screen. Note: Since multiple edits in one day may still happen to pages, they can be grouped on the recent changes page by enabling "Group changes by page in recent changes and watchlist" in the recent changes tab in the user preferences.
  • Please correct all typos found, even if changing the sentence layout is necessary. Comprehension is important.
  • Run a spell check of the article to catch spelling errors.

Page layout guidelines and creation of new pages

  • Typically, a page will start with a short intro, then the content of the page, a history section, and a "see also" section. Please follow this when creating content pages. Categories should be used sparingly.
  • Please use sane formatting, and do not Capitalize Words Like This, or L I K E T H I S.
  • Do not overuse bold, italics, or colorful text. This detracts from the effect of said text when it is actually necessary.
  • If possible, clean white-space from the ends of lines/pages. Many editors can do this for you. Emacs, Notepad++, Sublime Text, and Vim are recommended. This reduces the size of the page.
  • Avoid creating unnecessary pages. If the info you are trying to add is related to an entity in-game, please place the info on that entity's page, and so on and so forth.
  • See the Editor noticeboard for guidelines on whether the wiki is currently targeting the stable or experimental version of the game.
  • Upcoming features should be referenced with a link to a comment or image posted by a member of Factorio's development staff.
  • Mod related documentation is not to be hosted on this wiki. The Official Factorio Wiki is meant for documentation of the base game only. Instead, users looking for documentation or developers looking to provide documentation should do so on their mod's entry in the mod portal, or bundle the documentation with the source code of the mod. This wiki does not document nor enumerate mods.
  • Edit in an “encyclopedia” style, avoiding use of the first person or any personal bias. Avoid words like I, me, you, etc.
  • Do not create circular links, I.e. do not link a page to itself. While this doesn't do anything, it adds noise to the page that editors have to ignore.
  • If making a comment to other editors is necessary, place the comment in comment delimiters, <!-- Comment --> so it cannot be seen by users. This is only necessary to explain the page's specific formatting, such as seen on News.

The History section

  • This Wiki uses a history section on all content pages to track when entities/items are changed in the game. To do this, the Wiki uses the history template, which provided automatic formatting and version linking.
  • Bugs and bug fixes must not be placed in the update history section of a page, except for very significant instances. Instead, please document bugs in the bug sections of the official forums. However, bug fixes may be documented on Version history pages.
  • While a history section is not required for information pages such as Railway, all content pages concerning entities or mechanics of the game should have a history, taken from the changelog file provided with a standard Factorio install. The {{history}} template will automatically link to the relevant page in Version history.
  • Trivia and general facts are allowed, as long as it does not contain personal opinion and is not conjecture.

Media

  • When possible, avoid putting important text in images, as it is not search-able, and makes finding that info harder.
  • When uploading an image, please use a descriptive, unique name, and fill out the description box. Images given a non-descriptive name will be renamed.
  • When uploading an updated version of an image, use the "upload a new version of this image" link found on the old file's page. This ensures that all old instances are updated automatically.
  • Please mark any duplicated files for deletion with the {{delete}} template. If approved, an admin will delete them. Requests for pages in the requesting user's namespace are always granted.
  • If uploading images that are not of Factorio, please ensure you hold rights to upload the image. We don't want to get DMCA requests.
  • Gifs of mechanics are allowed and encouraged.
  • Please ensure that the image you are uploading is of good quality. Use the PNG filetype when possible.
  • See the section below for more info on uploading images.

Templates

  • Templates are to be used for formatting/common text on many pages. Do not create templates for only a few pages, except for special circumstances.
  • Templates should include {{documentation}} inside of noinclude tags, and should have a /doc sub-page to describe the use of the template.
  • Avoid making many sequential edits to a commonly used template. This creates strain on Wube's servers to update across all the pages. Preform edits to those templates with a single edit only. If you need to edit a protected template, please contact an admin, as these templates are especially heavily used.
  • Templates should be light, contain little content, and have descriptive names.
  • Templates must be created within the Template namespace. Please read up on this if you don't know what this means.

Page protection

  • Typically, pages with high amounts of transclusions/importance will be protected, to both protect against vandalism, and to protect the servers from load caused by edits to these pages.
  • If an editor needs to make a change to one of these protected pages, please contact an admin.
  • If you encounter a page that you feel should/should not be protected, please contact an admin and explain your reasoning.
  • We do not protect userspace pages, nor tutorials, as it is unfriendly to those who seek to fix mistakes.

Pictures

Picture formats

  • (100 - 200) x (100-300) px
For flowing with the text, pictures which explain the text, the browser can embed this into it's own rendering. You can put them left or right, the text should flow around.
  • (400 - 600) x (100 - 600) px
Something like a banner. A big picture which stays alone in its line. You may put simply a ":" in front of it to indent the picture and keep it away from flowing text.
  • 300 x 300 px
This is especially good for gif animations. Gif animations cannot be reduced in size, because Mediawiki re-renders the picture and the result is the first frame of the gif!
  • The biggest format for flowing text should be: 600x600px

To re-size an image when it's put onto a page, simply provide the size as an argument to the file:

[[File:example.png|200x200px]]

Making pictures out of the game

Do's:

  • Take pictures at day! Use night or dawn only if you need to explain something that only works at night (for example, the lights).
  • Turn off clouds! The shadows in GIF-animations are not useful.
  • Steam/smoke is also not that useful.
  • Use god mode! [1]. You can move anywhere on the map and your character won't be in the picture.
  • You can slowdown the game to find the right moment for the picture. Slowdown is also useful if you use Gifcam, which makes Screenshots in 30 frames/sec only.
  • You can also use the peaceful mode to be not disturbed by the natives.
  • You can stop the game in the right moment using SHIFT-SPACE key. That also blends the grid in.
  • Learn how to use the Debug mode to add relevant information into the picture.
  • Go into the highest zoom level you possibly can without missing any vital information.
  • A good in-game picture should be rebuilt so that only the relevant entities/items are shown. Anything in the photo other than what you're trying to show/explain is unnecessary.

Dont's:

  • Don't take pictures of clutter! The only stuff in the photo should be the stuff you're trying to show. The exception to clutter: If you're showing what a fully finished factory or setup might look like.
  • Don't just take a screenshot. Try to remove all unneeded information from the picture.
  • Try to make a picture without the character, except if to show something; then face the character toward it.

See http://www.factorioforums.com/forum/viewtopic.php?f=6&t=2472 for more.

Taking Screenshots, animations and videos

Taking Screenshots

Optimizing the picture before upload

  • Cut as much as possible/nice.
  • Resolution should not normally be higher than 600x600 px. Use multiple photos or ask a trusted wiki user if you need a much larger photo.
  • Do not add text to the photos Write any needed text outside the photo on the wiki. You cannot search text that is in a photo and users might not find what they are looking for.
  • Sharpen the pictures. For the wiki it looks a lot better to sharpen the pictures once or twice.