Factorio:Style guide: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(removed point that would be duplicate with a rule)
(→‎Media: updated with new graphics settings)
 
(17 intermediate revisions by 6 users not shown)
Line 1: Line 1:
This is the official Factorio style guide. Please follow this guide and the [[Factorio:Wiki rules|rules]] when creating or editing pages and files on this wiki. Unlike the rules, not following this guide will not be punished, however it is still highly encouraged to follow it.
This is the official Factorio style guide. Please follow this guide and the [[Factorio:Wiki rules|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 ==
== 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.
* 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 [[Factorio:Editor noticeboard|Editor noticeboard]] for guidelines on whether the wiki is currently targeting the stable or experimental version of the game.
* See the [[Factorio:Editor noticeboard|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 [[News|Factorio Friday Facts]] usually show plans and not confirmed changes, so information should not be treated as such.
* [[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 [[News|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 <code><nowiki>{{archive}}</nowiki></code> template and not be edited any further.
* Pages about removed content should be marked with the <code><nowiki>{{archive}}</nowiki></code> template and not be edited any further, except to remove redlinks or outdated categories.


== Language ==
== 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.
* 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.
* Correct all typos found, even if changing the sentence layout is necessary. Comprehension is important.
Line 17: Line 15:
* Items, entities, and other in-game objects should be named and translated according to the official in-game translations.
* 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]].
* To automatically translate page names, infoboxes and similar templates, use [[Template:Translation]].
** See also the ''[[Factorio:Translation guide|translation guide]]''.


== Page layout and formatting ==
== 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.
* 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.
* 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 <span style="color:#00FF00">colorful text.</span> This detracts from the effect of said text when it is actually necessary.
* Do not overuse '''bold''', ''italics'', or <span style="color:#DDFF66">colorful text.</span> This detracts from the effect of said text when it is actually necessary.
* Usually <code><nowiki>[[iron gear wheel]]s</nowiki></code> is preffered over the piped version which would be <code><nowiki>[[iron gear wheel|iron gear wheels]]</nowiki></code>.
* Usually <code><nowiki>[[iron gear wheel]]s</nowiki></code> is preferred over the piped version which would be <code><nowiki>[[iron gear wheel|iron gear wheels]]</nowiki></code>. Any text can be placed immediately after a link to become part of the link.  
* 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.
* 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, <code><nowiki><!-- Comment --></nowiki></code> so it cannot be seen by users. This is can be necessary to explain the page's specific formatting, such as seen on [[News]].
* If making a comment to other editors is necessary, place the comment in comment delimiters, <code><nowiki><!-- Comment --></nowiki></code> so it cannot be seen by users. This can be necessary to explain the page's specific formatting, such as seen on the [[news]] page.
* 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 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. For info on how to bold words, see [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Formatting the help page on formatting].
* The first instance of an item name on a page can be linked, via double brackets (eg. <code><nowiki>[[copper plate]]</nowiki></code>). 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.  
* The first instance of an item name on a page can be linked, via double brackets (eg. <code><nowiki>[[copper plate]]</nowiki></code>). Further mentions of the same item should generally only be re-linked if the second link is more than a page-length away from the original.


=== Capitalization ===
=== Capitalization ===
* Only the first letter and proper nouns such as "Nauvis" should be capitalized in section headings or page names.
* 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.  
* In-game items, entities, 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 <code><nowiki>[[iron plate]]</nowiki></code> and not <code><nowiki>[[Steam engine]]</nowiki></code>.
* When linking to another page within a flowing text, use normal capitalization for the link. For example: <code><nowiki>"in order to craft [[iron gear wheel]]s, [[iron plate]]s must..."</nowiki></code> and ''not'' <code><nowiki>"in order to craft [[Iron gear wheel]]s, [[Iron plate]]s must...</nowiki></code>. Remember that the first letter is automatically capitalized to resolve the page when the link is clicked.


=== The history section ===
=== 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 [[Template:History|history]] template, which provides automatic formatting and version linking. The header for this section should be <code><nowiki>== History ==</nowiki></code>.
* 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 [[Template:History|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 itself and not in its history section. However, bug fixes ''are'' documented on [[version history]] pages, since they are part of the official changelog.
* 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 behaviour 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 offical 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 [[Template:History|history template]] will automatically link to the relevant page in [[version history]].
* 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 <code><nowiki>{{history}}</nowiki></code> 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 or conjecture. These facts should be placed in a specific "Trivia" section. If possible, (such as detailing information provided by a dev through official channels) provide a source link.
* 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 [[Factorio:translation guide|translation guide]] for further information.


== Media ==
== 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.
* 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.
* 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.
** 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. Images given a non-descriptive name will be renamed.
* Item icons should be named after their English in-game name.
* 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.
* 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 <code><nowiki>{{delete}}</nowiki></code> template. If the request is approved, an admin will delete them. Requests for deletion of pages in the requesting user's namespace are always granted.
* Please mark any duplicated files for deletion by placing the [[Template:Delete|deletion template]] on the page: <code><nowiki>{{delete}}</nowiki></code>.
* If uploading images that are not of Factorio, please ensure you hold rights to upload the image.
* If uploading images that are not of Factorio, please ensure you hold rights to upload the image.
* Gifs of mechanics are allowed and encouraged.
* 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.
* Please ensure that the image you are uploading is of good quality. Use the PNG filetype when possible.
* See the section [[#Pictures|below]] for more info on uploading images.
* All in-game sprites/icons that were retrieved directly from the game source 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.
* 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.


=== Taking screenshots of the game ===
=== Taking screenshots of the game ===
 
* Place <code><nowiki>{{Screenshot}}</nowiki></code> 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).
* 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 off clouds, smoke and animated trees! The shadows distract from the actual content of the image.
* Turn on info ({{Keybinding|alt}})
* Reset brightness, contrast and saturation to default in the graphics settings.
* Use god mode! [http://lua-api.factorio.com/latest/LuaPlayer.html#LuaPlayer.set_controller]. You can move anywhere on the map and your character won't be in the picture.
* Turn on {{Keybinding|alt}} mode.
* It is possible to take large screenshots using a [[Console#Large_Screenshots|console command]].
* Use [[Console#Enable_god_mode|god mode]] or the [[map editor]]! You can move anywhere on the map and your character won't be in the picture.
* You can [http://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.speed slow down the game] to find the right moment for the picture.
* It is possible to take large screenshots using a [[Console#Large_Screenshots|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.
* Learn how to use the [[Debug mode]] to add relevant information into the picture, such as showing rail blocks.
* You can [[Console#Change_game_speed|slow down the game]] or pause the game in the map editor to find the right moment for the picture.
* Go into the highest zoom level you possibly can without missing any vital information.
* Go into the highest zoom level you possibly can without missing any vital information.
* A good in-game picture should be build 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.
* 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.
* Crop pictures to show only what you want to show.
* Try to make a picture without the character, except if to show something; then face the character toward it.
* 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 300×300px in size.


== Templates ==
== 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 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 <code><nowiki>{{documentation}}</nowiki></code> inside of noinclude tags, and should have a /doc sub-page to describe the use of the template.
* Templates should be have their use described using [[Template:Documentation]] by including it in the template code: <nowiki><noinclude>{{doc}}</noinclude></nowiki>
* 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.
* 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 ==
== See also ==
* [[Factorio:Wiki_rules|The rules]]
* [[Factorio:Wiki_rules|The rules]]

Latest revision as of 11:29, 3 December 2021

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]]. Any text can be placed immediately after a link to become part of the link.
  • 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 the news page.
  • 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. For info on how to bold words, see the help page on formatting.
  • 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 only be re-linked if the second link is more than a page-length away from the original.

Capitalization

  • Only the first letter and proper nouns such as "Nauvis" should be capitalized in section headings or page names.
  • In-game items, entities, and other in-game object names are common nouns and should not be capitalized unless they start a new sentence.
  • When linking to another page within a flowing text, use normal capitalization for the link. For example: "in order to craft [[iron gear wheel]]s, [[iron plate]]s must..." and not "in order to craft [[Iron gear wheel]]s, [[Iron plate]]s must.... Remember that the first letter is automatically capitalized to resolve the page when the link is clicked.

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 provides automatic formatting and version linking. The header for this section should be == History ==.
  • 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 itself and not in its history section. However, bug fixes are documented on version history pages, since they are part of the official changelog.
  • 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 or conjecture. These facts should be placed in a specific "Trivia" section. If possible, (such as detailing information provided by a dev through official channels) provide a source link.
  • 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. 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 by placing the deletion template on the page: {{delete}}.
  • 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.
  • All in-game sprites/icons that were retrieved directly from the game source 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 {{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, smoke and animated trees! The shadows distract from the actual content of the image.
  • Reset brightness, contrast and saturation to default in the graphics settings.
  • Turn on ALT mode.
  • Use god mode or the map editor! 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 or pause the game in the map editor 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 300×300px 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 be have their use described using Template:Documentation by including it in the template code: <noinclude>{{doc}}</noinclude>
  • 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