View source for Help:Style guide

{{WIP}}
To keep a consistent look and feel throughout the wiki, it is highly recommended to follow the style guidelines presented on this page.

Wikipedia already offers a general [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style style manual], though further guidelines are required for ''Vintage Story'' related articles. This page will reiterate a handful of concepts covered in the aforementioned manual to facilitate the definition of this wiki's look and feel.


=== Article names ===
Article names should generally be in the singular form. Never prefix them with ''The'', ''A'', ''An'' or so on, unless it is part of the name, such as most of the game update names. The name should follow normal phrase capitalization unless it is a proper noun.

* reflect the name of the item in the game, for example: 'Ore blasting bomb' not 'Bomb'.
* be complete noun or verb phrases, for example: 'Tool Strength Chart' not 'Chart: Tool Strength'.
* '''In English:''' singular nouns. For example, the page is "Axe", not "Axes", and "Berry", not "Berries".

== Titles ==
Section and article titles should both be written in '''sentence case''', where only the first word is capitalized, unless they contain proper nouns. This is because MediaWiki automatically capitalizes the first letter of links. Therefore, when trying to insert links into sentences, it is far easier if the page title in question is in sentence case. For example, if the page on helve hammers was titled <code><nowiki>Helve hammer</nowiki></code>:

: <code><nowiki>One example of a mechanism is the [[helve hammer]].</nowiki></code> 

But if the page was titled <code><nowiki>Helve Hammer</nowiki></code>:

: <code><nowiki>One example of a mechanism is the [[Helve Hammer|helve hammer]].</nowiki></code>

This greatly simplifies adding links and avoids incorrect capitalization.

=== Section headings ===
Section headings should always follow sentence style capitalization. Main sections in an article should have a level 2 heading (<code>== Heading ==</code>) and increase by one for any sub-sections. Avoid using too many unique sections if possible, as the Table of Contents can quickly become too crammed.

== Writing ==
Wikis are used to present facts to the reader, so avoid including any personal theories, opinions, or subjective concepts when writing an article. All information presented should be traceable to a reliable source of some kind. Most articles should be written in the third-person and avoid any terms that refer to the reader directly ("you", "your", etc.), though this rule does not need to be followed in the case of guides or tutorials.

Always try to formulate full, descriptive sentences when writing an article, especially in the summary (eg. "'''Knives''' are tools used to harvest [[grass]], [[Cooper's Reed (Cattail)| cattails]], and [[Wild Foods|wild foods]] including meat from animals." instead of "A tool that can harvest things.").

=== Capitalization ===

==== Items, blocks and mobs ====
All item (materials, weapons, tools, etc.), block and mob names are considered common nouns and should not be capitalized unless it is at the beginning of a sentence.

==== Game ====
''Vintage Story'' should always follow title case capitalization, as well as formal update names (eg. [[The De-Jank and Game Juice Update]]). Gamemodes like [[Survival]] or [[Creative]] should also be capitalized.

=== Emphasizing ===
When emphasizing certain words, always use ''italics'', and not '''bold''' (''uses of bold lettering in this article notwithstanding''). The latter should be almost exclusively used for the initial mention of the article name in the summary. Italics can be used for single word emphasis, or brief full-sentence notes if additional secondary information relating to the text preceeding it seems preferable.

The game's title should always be emphasized with italics as well, though "Vintage Story Wiki" should not.

== Linking ==
Where appropriate, topics relating to ''Vintage Story'' should be made into links, as long as this doesn't negatively affect article readability. Ultimately, the goal is to neither overlink, nor underlink, as either can negatively impact the reading experience.

Here are some general loose guidelines when it comes to linking in an article:

* Generally, a link should only appear ''once'' in an article, but may appear multiple times if helpful to the reader. This applies more heavily to larger articles, where links are more likely to no longer be visible on a users' screen as they scroll. Providing repeat links this way can help prevent frustration and the need to use the search bar if and when they may want to read on about a related topic.
* Two links should not be immediately next to each other, as this can cause them to appear as a single link instead. If you feel it necessary to use both links, either try to rephrase or - when applicable - use a single, larger link instead (eg. {{ll|Stone Blocks|stone blocks}} instead of {{ll|Stone|stone}} {{ll|Blocks|blocks}}).
* To preserve sentence case, where applicable, use piped links (<code>Apples are a type of <nowiki>{{ll|Fruit|fruit}}</nowiki></code>).
* Use [[Template:Localized_link]] for all of your links to make {{ll|Vintage Story Wiki:How to translate the wiki|translating}} them easier.<br>Examples: <code><nowiki>{{ll|Leather}}</nowiki> is used to make a backpack.</code> or <code>Learn <nowiki>{{ll|Starter Guide|how to play}}</nowiki>.</code>

== Redirects ==
Redirects help readers find pages that may have many common synonyms, or where the topic in question is covered as a subsection of a larger page. Redirects should be used where a short stub page would be inappropriate, or where that topic is already covered in depth on another page. For example, instead of having a page for every type of flower, common flower names should redirect to the central <nowiki>[[Flower]]</nowiki> page, as each individual flower type barely differs from the others. However, in the case of items like any <nowiki>[[Fruit|fruit]]</nowiki>, an individual page for each is preferred, as a sufficient amount of info can be presented for each.

Example: a page for blue lupine would contain
<pre><nowiki>#REDIRECT [[Flower]]</nowiki></pre>
That's it!

This is ''not'' a place to use the localized link template: <code><nowiki>{{ll|page|display text}}</nowiki></code>.

''Note: the wiki currently has an extension installed which replaces the display text of redirect pages with their destination page instead. For the time being, and if applicable, use piped links with a lowercase display name and a space in order to display the appropriate link text'' (eg. <nowiki>[[Trunk| trunk]]</nowiki>).

== Article layout ==
Unless an article fits into a more defined style guide (such as [[Vintage_Story_Wiki:Style_guide/Versions|Style_guide/Versions]]), almost all pages on the site should attempt to follow the following layout, in order:

# '''Hatnotes''': short notes at the very top of a page, to help readers locate a different article if the one they are at is not the one they're looking for
# '''[[:Category:Notice_templates|Notice templates]]''': such as {{Tl|WIP}} or {{Tl|Outdated}}
# '''[[:Category:Infobox_templates|Infobox]]''': if applicable, an image and basic data
# '''Summary''': a general overview of the page's subject, very brief 
# '''Creation/Obtaining''': what process the player needs to undergo in order to acquire the object in question
# '''Usage''': the uses of the respective object, i.e. uses in other crafting recipes, world interactions, etc.
# '''Contextual sections''': any further sections needed that would help provide extra information about the subject
# '''[https://www.vintagestory.at/blog.html History]''': all changes relating to the page's subject throughout all game versions
# '''Notes''': extra notes pertaining to the page's subject that do not fit in the rest of the article
# '''[https://wiki.vintagestory.at/index.php/Special:Upload Gallery]''': supplementary images of the subject
# '''[https://en.wikipedia.org/wiki/Help:Link See also]''': links to other closely related topics
# '''References''': a list of all references made in the article to point towards external sources of info
# '''Navbox''': if applicable, a fitting Navbox, such as {{Tl|Game navbox}}
<br>
Certain articles might fit into particular article categories which have received unique style guides that do not fully respect the above layout order. These unique style guides are:
* [[Vintage_Story_Wiki:Style_guide/Versions|Versions]]
<br>
Items 1-4 in this layout order should probably be above a page's Table of Contents, with items 5-12 formatted as [https://meta.wikimedia.org/wiki/Help:Wikitext_examples#Organizing_your_writing section headings].
<br>
<br>
When adding to a History section, use the same citation format as [[Versions#References|References]].  
<br>Put newer information below older entries.  The [Bear] page has an example of formatting you might want to use, but simple bullet points work fine.

== Categories and templates ==

=== Categories ===
If manually adding categories, include them at the very end of an article. Categories should follow sentence case capitalization, and be '''collective (plural) nouns''' (e.g. "Metals" instead of "Metal"). Categories on pages that are marked for translation will need the addition of the <code><nowiki>{{#translation:}}</nowiki></code> tag. A category should be a broad group in which the subject of an article can be placed. For example, [[Pickaxe|pickaxe]] would fit in both [[:Category:Items]] and [[:Category:Tools]].

All current categories are listed on the [[Special:Categories]] page.

If you feel a new category is needed, you can freely add a category link on any page - creating the category page itself is not necessary. However, keep in mind that category names should generally be plural, unlike article names.

=== Templates ===
A number of templates are available to improve the readability and presentation of the wiki. Generally speaking, most editors need not worry about editing templates, though if you feel like a new template would be beneficial for the wiki and you're not well-versed in template creation, please first request it on the [[Vintage Story Wiki:Community noticeboard|community noticeboard]]. We try to give a majority of the wikis' templates a similar styling.

When making a template, there are just a handful of rules to be aware of:
* Do not make templates that heavily clash with the general presentation of the wiki.
* A {{Tl|doc}} page should always be included, even if the template is self-explanatory.
** ''Read [[Template:Documentation|Help:Template_documentation]] if you're unsure about what info to include''
* Any categories relating to the ''template itself'' should be included on the documentation page, within a <code><nowiki><includeonly></includeonly></nowiki></code> tag.
* If a template should apply a category to pages it is transcluded to, the same as above applies, but placed on the template page instead.

A list of all templates can be found on the [[:Category:Templates]] page.

==== Notice templates ====
A handful of [[:Category:Notice_templates|notice templates]] exist in order to facilitate the work done on the wiki, and direct editors to pages that need attention in some form. 

* {{Tl|Delete}}
* {{Tl|Move}}
* {{Tl|Outdated}}
* {{Tl|Placeholder}}
* {{Tl|Stub}}
* {{Tl|WIP}}

== See also ==

* [[Vintage_Story_Wiki:How_to_translate_the_wiki|How to translate the wiki]]

{{Editing navbox}}

[[Category:Style guides]]
[[Category:Wiki editing]]