Help:Style guide

From Vintage Story Wiki
UnderCon icon.png

This page is under construction.
This page is being created, or is in the process of extensive expansion or major restructuring. Until this notice is removed, please do not translate this page. Expect the content of this page to change significantly.


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 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 wikis' 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 Helve hammer:

One example of a mechanism is the [[helve hammer]].

But if the page was titled Helve Hammer:

One example of a mechanism is the [[Helve Hammer|helve hammer]].

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 (== Heading ==) 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, cattails, and 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 games' 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. stone blocks instead of stone blocks).
  • To preserve sentence case, where applicable, use piped links (Apples are a type of [[Fruit|fruit]]).

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 Flower page, as each individual flower type barely differs from the others. However, in the case of items like any fruit, an individual page for each is preferred, as a sufficient amount of info can be presented for each.

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. trunk).

Article layout

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

  1. Hatnotes
  2. Notice templates
  3. Infobox
  4. Summary: a general overview of the page's subject
  5. Creation/Obtaining: what process the player needs to undergo in order to acquire the object in question
  6. Usage: the uses of the respective object, i.e. uses in other crafting recipes, world interactions, etc.
  7. Contextual sections: any further sections needed that would help provide extra information about the subject
  8. History: all changes relating to the page's subject throughout all game versions
  9. Notes: extra notes pertaining to the page's subject that do not fit in the rest of the article
  10. Gallery: supplementary images of the subject
  11. See also: links to other closely related topics
  12. References: a list of all references made in the article to point towards external sources of info
  13. Navbox: if applicable, a fitting Navbox, such as {{Game navbox}}

Certain articles may fit into particular article categories which have received unique style guides that do not fully respect the previous layout order. These unique style guides are:

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 {{#translation:}} tag. A category should be a broad group in which the subject of an article can be placed. For example, 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 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 {{doc}} page should always be included, even if the template is self-explanatory.
  • Any categories relating to the template itself should be included on the documentation page, within a <includeonly></includeonly> 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.

Maintenance templates

A handful of maintenance templates exist in order to facilitate the work done on the wiki, and direct editors to pages that need attention in some form.

See also


Editing articles
Hubs Community noticeboard
Guides How to helpHow to translate the wiki
Styling Style guideVersions