Factorio:Style guide

From Official Factorio Wiki
Revision as of 12:43, 6 December 2018 by Bilka (talk | contribs) (→‎Taking screenshots of the game: document some stuff)
Jump to navigation Jump to search

This is the official Factorio style guide. Please follow this guide and the rules when creating or editing pages and files on this wiki. Unlike the rules, failure to follow this guide will not be punished, however it is still highly encouraged to follow it.

Page creation and upcoming/outdated content

  • Avoid creating unnecessary pages or subpages. If the info you are trying to add is related to an entity in-game, please place the info on that entity's page.
  • 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. Please consider that the Factorio Friday Facts usually show plans and not confirmed changes, so information should not be treated as such.
  • Pages about removed content should be marked with the {{archive}} template and not be edited any further, except to remove redlinks or outdated categories.

Language

  • Edit in an “encyclopedia” style, avoiding use of the first person or any personal bias. Avoid words like I, me, you, etc. The tutorial namespace is exempt from this guideline.
  • Correct all typos found, even if changing the sentence layout is necessary. Comprehension is important.
  • 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 and in the page history.
  • 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.
  • Only translate pages if you fluently speak the language you are translating to.
  • Items, entities, and other in-game objects should be named and translated according to the official in-game translations.
  • To automatically translate page names, infoboxes and similar templates, use Template:Translation.

Page layout and formatting

  • 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.
  • Usually [[iron gear wheel]]s is preferred over the piped version which would be [[iron gear wheel|iron gear wheels]].
  • Do not create circular links, I.e. do not link a page to itself. This also means that a page should not link to a redirect that links to the page itself.
  • If making a comment to other editors is necessary, place the comment in comment delimiters, <!-- Comment --> so it cannot be seen by users. This can be necessary to explain the page's specific formatting, such as seen on News.
  • The first instance of the page title should be bold. This should usually be in the first sentence of the article. No other instance of the page title should be bold. To make a word or phrase bold, place three apostrophes (') on each side.
  • The first instance of an item name on a page can be linked, via double brackets (eg. [[copper plate]]). Further mentions of the same item should generally not be linked, though multiple identical links can exist if they occur far from each other and would be helpful to readers.

Capitalization

  • Only the first letter and proper nouns such as "Nauvis" should be capitalized in section headings or page names.
  • The in-game items, entity, and other in-game object names are common nouns and should not be capitalized unless they start a new sentence.
  • Likewise, when linking to another page within a flowing text, use normal capitalization for the link, so [[iron plate]] and not [[Steam engine]].

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. Any kind of bug should be reported on the forums and has no place on the wiki unless it is deemed "not a bug" by the developers. In that case the specific behavior should be documented on the page, but not in the history section. However, bug fixes are documented on Version history pages, since they are part of the official changelog which is reflected on those 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. This facts should be placed in a specific "Trivia" section.
  • The history section should not be included in translated pages. Likewise, the version history is not to be translated. See the translation guide for further information.

Media

  • When possible, avoid putting important text in images, as it is not search-able, and makes finding that info harder. The text also can not be translated, so each language would need its own version of the image.
    • If a translated version of an image is needed, please upload it under the same name as the original image, with your language suffix at the end, e.g. (Programmable_speaker_ui.png in German -> Programmable_speaker_ui-de.png)
  • 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.
  • Item icons should be named after their English in-game name.
  • 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 uploading images that are not of Factorio, please ensure you hold rights to upload the image.
  • 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.
  • Video guides or tutorials should not be placed in the main wiki, however links to them are allowed in the "See also" section of pages.
  • All in-game images/icons that were retrieved directly from the game files need to have Template:Game image on their file page. This is essential to indicate that you do not own the copyrights of the image.

Taking screenshots of the game

  • Place Template:Screenshot in the file description when uploading it.
  • 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 and smoke! The shadows distract from the actual content of the image.
  • Turn on info (ALT).
  • Use god mode! You can move anywhere on the map and your character won't be in the picture.
  • It is possible to take large screenshots using a console command. For example: /c game.take_screenshot{{x=1024, y=1024}, showgui=false, show_entity_info=true, zoom=2} takes pixel perfect screenshots with the new high resolution graphics.
  • You can slow down the game to find the right moment for the picture.
  • Go into the highest zoom level you possibly can without missing any vital information.
  • A good in-game picture should be built so that only the relevant entities/items are shown. Anything in the photo other than what you are trying to show/explain is unnecessary clutter.
  • Crop pictures to show only what you want to show.
  • Try to make a picture without the character unless the character is the subject of the screenshot.
  • Don't use .jpg / .jpeg as a fileformat as you will lose detail.
  • Use the high resolution sprites!
  • For images to be used in an infobox: Use zoom level 2 and try to make it 300x300 in size.

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. Perform 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.

See also