Help:Style manual: Difference between revisions

Jump to navigation Jump to search

Help:Style manual (view source)

Revision as of 01:43, 10 March 2024

13,534 bytes added ,  10 March
m
typo
m (typo)
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{PageSeo
{{PageSeo
| title = Style Guide
| title = Style manual
| image =  
| image =  
| description = A style reference for Baldur's Gate 3 Wiki contributors.
| description = A style reference for Baldur's Gate 3 Wiki contributors.
}}
}}
{{NavWiki|help}}
{{NavWiki|help}}
{{TocStyle}}
This is BG3.Wiki's '''style manual'''. It serves as a style reference for contributors to the wiki, and is regularly updated and maintained as necessary.
This is BG3.Wiki's '''style manual'''. It serves as a style reference for contributors to the wiki, and is regularly updated and maintained as necessary.


Line 21: Line 20:
* Names of articles about classes of things are generally given in plural form ([[ability scores]], [[dice rolls]]).
* Names of articles about classes of things are generally given in plural form ([[ability scores]], [[dice rolls]]).
* Names of articles about things which are generally expressed as multiples are also given in plural form ([[hit points]]).
* Names of articles about things which are generally expressed as multiples are also given in plural form ([[hit points]]).
* Names of categories should always be given in plural form.
* Names of [[Help:Categories|categories]] should usually be given in plural form.


=== Specific guidelines ===
=== Specific guidelines ===
Line 56: Line 55:
==== Subpages ====
==== Subpages ====
Except when implemented as part of internal navigation on a page (such via the {{t link|CombatTab}} template), subpages should be avoided.
Except when implemented as part of internal navigation on a page (such via the {{t link|CombatTab}} template), subpages should be avoided.
Subpages should generally not be capitalised.


== Article layout ==
== Article layout ==
Line 63: Line 64:
# {{t link|DISPLAYTITLE}}
# {{t link|DISPLAYTITLE}}
# {{t link|hatnote}}
# {{t link|hatnote}}
# Content warnings: {{t link|cw}}
# Notices: {{t link|Priority}}, {{t link|Stub}},  {{t link|Under construction}}, {{t link|Rewrite}}.
# Notices: {{t link|Priority}}, {{t link|Stub}},  {{t link|Under construction}} or {{t link|Rewrite}}.
# Content and spoiler warnings
# Infoboxes: {{t link|CharacterInfo}}, {{t link|relative location}}
# Tab template: {{t link|Companion tab}}, {{t link|Combat tab}}
# Infoboxes: {{t link|Infobox character}}, {{t link|Infobox statistics}}, {{t link|relative location}}
# Images
# Images
# Tab template: {{t link|CompanionTab}}, {{t link|CombatTab}}
# Introduction: A brief and spoiler-free summary of the article's contents that gives context to the article.
# Introduction: A brief and spoiler-free summary of the article's contents that gives context to the article.
# TOC template: {{t link|TOC}}
# TOC template: {{t link|TOC}}
# {{t link|SpoilerWarning}}, if applicable.
# Body: Most of article's contents (see [[Help:Style manual#Body|below]]).
# Body: Most of article's contents (see [[Help:Style manual#Body|below]]).
# Achievements: A section with an {{t link|achievement}} template.
# Achievements: A section with an {{t link|achievement}} template.
Line 97: Line 97:


===== Characters =====
===== Characters =====
Character articles typically have a {{t link|CharacterInfo}} template and a {{t link|CompanionTab}} or {{t link|CombatTab}} template.
Character articles typically have a {{t link|Infobox character}} template, {{t link|Infobox statistics}} template, and a {{t link|Companion tab}} or {{t link|Combat tab}} template.
# Overview
 
## Background: Contextual information about the character's role in the game.
=====Origins or permanent companions=====
## Description: A basic description of the character, including their personality, appearance and noteworthy traits.
# Overview: A brief summary of the article as a whole for quick access to specific information.
## Personal quest: A spoiler-light overview of the character's personal quest (if applicable) or involvement in quests.
## Background: A brief introduction to the character and their role in the game.
## Recruitment
## Starting class: A short overview of their starting class and default subclass choices, if applicable.
## Approval
## Special features: Any special features available only to this character.
# History
## Personal quest: A spoiler-light summary of the character's personal quest.
# A quest section, often named after the character's personal quest, that contains major spoilers.
## Recruitment: Where and how the character can be recruited. If multiple options are available, group them by act.
# List of interactions
## Approval: A short guide to what the character generally approves and disapproves of.
# Loot
## Romance: Indicate whether the character can be romanced or not, with a short summary of the relationship's progression or themes.
# Description
## Appearance: How the character looks and dresses.
## Personality: How the character is like, their behaviour, expressions, etc.
# History: The character's backstory before the events of the game. Particularly long history sections can be broken down into relevant subsections.
# Involvement: The character's involvement in the story, as seen by the player and the party. Contains major spoilers.
## Name of personal quest: This section describes the events of the character's personal quest. Can be further broken into acts.
## Endings: All of the character's possible story endings.
# Quest rewards: Any quest rewards the character may receive during their personal quest and related sub-quests.
# Interactions: A brief listing of all interaction events with the character (events where the character has an exclamation mark above their head), grouped into acts.
# Loot: Whether the character can be killed or not, and if so, the loot the character carries by default.
## Starting equipment: The character's starting equipment when recruited or playing as an origin, if applicable.
 
=====Non-player characters=====
# Overview: A brief summary of the article as a whole for quick access to specific information.
## Background: A brief introduction to the character and their role in the game.
## Gameplay: A bulleted list of the character's gameplay role (vendor, boss, where they are found, etc.).
## Quests: Any quests that the character is involved in.
## Related quest rewards: Any items that the character may reward for completing a quest.
# Description
## Appearance: How the character looks and dresses.
## Personality: How the character is like, their behaviour, expressions, etc.
# History: The character's backstory before the events of the game. Particularly long history sections can be broken down into relevant subsections.
# Involvement: The character's involvement in the story as seen by the player and the party, broken down into encounters per act.
# Combat: A section describing any combat encounters with this character. Long combat sections, especially for boss encounters, should be moved to a combat subpage.
## Spells and abilities: Abilities and spells used by the character in combat.
## Loot: Any items that can be looted from the character.


===== Locations =====
===== Locations =====
Line 149: Line 175:
# Instructions for any additional steps necessary to find or obtain the item (e.g. 'Jump up to the ledge behind the purple mushroom.')
# Instructions for any additional steps necessary to find or obtain the item (e.g. 'Jump up to the ledge behind the purple mushroom.')
# Map coordinates of the item, if applicable, in the format ''(X:123, Y:123)''
# Map coordinates of the item, if applicable, in the format ''(X:123, Y:123)''
#* This can be done in the form of the 'Coords' template: <nowiki>{{Coords|123|123}}</nowiki>
#* This can be done in the form of the {{t link|coords}} template: <nowiki>{{Coords|123|123}}</nowiki>


Lengthy instructions can be formatted with sublists, as necessary:
Lengthy instructions can be formatted with sublists, as necessary:
Line 193: Line 219:
Do not generally capitalise game concepts, mechanics, terminology or rules.
Do not generally capitalise game concepts, mechanics, terminology or rules.


Abbreviations should always be capitalised, such as: AC, DC, HP, STR, DEX, NPC.
The following abbreviations should always be capitalised: AC, DC, NPC and abbreviation of abilities (STR, DEX, CON etc).


Capitalise the following terms:
Capitalise the following terms:
Line 202: Line 228:
* Creature types (Aberration, Humanoid)
* Creature types (Aberration, Humanoid)
* Difficulty Class
* Difficulty Class
* The item categories Consumables, Miscellaneous and Valuables are capitalised.
* The item categories Consumables, Miscellaneous and Valuables are capitalised when used standalone.
* Specific abilities (Strength, Dexterity)
* Specific abilities (Strength, Dexterity)
* Specific actions (Attack action, Hide action)
* Specific actions (Attack action, Hide action)
Line 267: Line 293:


=== Semantic emphasis ===
=== Semantic emphasis ===
Use {{code|<nowiki>{{em}}</nowiki>}} or {{code|<nowiki><em>...</em></nowiki>}} for emphasis, for example to place emphasis (stress) on a certain word in a sentence, or to clarify the meaning of a sentence. In most cases, you should only use emphasis one <em>one</em> word per sentence. Never use apostrophes for emphasis.
Use {{code|<nowiki>{{em}}</nowiki>}} or {{code|<nowiki><em>...</em></nowiki>}} for emphasis, for example to place emphasis (stress) on a certain word in a sentence, or to clarify the meaning of a sentence. In most cases, you should only use emphasis on <em>one</em> word per sentence. Never use apostrophes for emphasis.


==== What to avoid ====
==== What to avoid ====
Line 349: Line 375:


== Terminology ==
== Terminology ==
=== Verbs ===
There are numerous conventions employed when describing things that a creature does:
* Creatures roll dice.
* Creatures deal damage..
* Creatures take actions.
* Creatures take turns.
* Creatures take rests.
* Creatures take damage.
* Creatures expend resources.
* Creatures expend spell slots.
* Creatures cast spell.
* Creatures attempt saves.
* Creatures attempt tasks involving ability checks.
* Creatures make ability checks.
* Creatures make saving throws.
* Creatures roll for initiative.
* Creatures inflict conditions.
* Creatures add modifiers to rolls.
* Creatures add bonuses to rolls.
* Creatures recover hp.
* Creatures improve abilities.
* Creature use weapons.
* Creatures use ability scores.
* Creatures have proficiency / are proficient with with weapons and armour.
* Creatures have proficiency/ are proficient in skills and saves.
=== Ability checks ===
=== Ability checks ===
The term "ability check" is preferred to the term "skill check", except when the distinction is important for clarity or brevity.
The term "ability check" is preferred to the term "skill check", except when the distinction is important for clarity or brevity.
Line 395: Line 448:


== Images ==
== Images ==
{{hatnote|See also: [[Help:Images]].}}
{{hatnote|Also see BG3Wiki's [[BG3Wiki:Image Policy|image policy]].}}
Images are frequently used on BG3Wiki, but correct usage is important for article quality. While images can be helpful in improving an article, textual contents of articles should function independently from its images. Images are added as an additional illustrative supplement.
 
=== Image usage ===
* Images should serve an informative and educational purpose, and should not merely be used for decorative or aesthetics reasons.
* Images should be both accurate and representative of the subject, whether it is a character, item, feature or a location.
* Articles should not rely on images in order to be understood – images should be supplementary to an article's textual contents.
 
=== Image placement ===
* Images should be in the relevant section, and should never be placed at the bottom of a section.
* Images should be in the relevant section, and should never be placed at the bottom of a section.
** Galleries are the bottom of pages are an exception.
* Do not refer the positioning of images in textual contents (eg. "in the image to the left" or "the image at the top".
* Do not refer the positioning of images in textual contents (eg. "in the image on the left", or "the image at the top".
 
* Textual contents of articles should function independently from its images. Images are added as an additional illustrative supplement.
=== Image sizes ===
* Add alt text to any images used in articles.
* Images should never use pixels for scaling, and should instead use the use the {{code|upright}} parameter (<nowiki>upright=scaling_factor</nowiki>), where scaling_factor is a number, usually 1.0, that uses the user's own image size preferences to scale the images. This value should never be above 1.3, and most of the time should be 1.0.
* Icons, such as this [[File:Concentration_Icons.png|20px]] Concentration icon should use pixels, usually between 16px and 32px.
** Inline usage of icons should generally set icons around 16px to 24 px.


==== Image alt text ====
=== Image alt text ===
When using the File template, alt text (text which appears when the image fails to load) should be added as necessary to improve accessibility. The text should be clear, concise and descriptive.
Alt text (text which appears when the image fails to load) should be added when using images in articles, since this is important for accessibility. The text should be clear, concise and descriptive.


Alt text can be added to the File template with this parameter:
Alt text can be added to the File template with this parameter:
Line 418: Line 481:
* <nowiki>{{File:Gale_Flirting.png|alt=Gale sings while sitting at lake.}}</nowiki>
* <nowiki>{{File:Gale_Flirting.png|alt=Gale sings while sitting at lake.}}</nowiki>


== Links ==
== Linking ==
Be careful not to underlink or overlink on the wiki. Generally, a link to a specific page should only appear once per article. Link the first instance of that word of an article.
Link to other articles when they have relevant additional information. Be careful not to underlink or overlink on the wiki. Only use links when they're helpful to the reader – every word that has an article does not need to be linked.
 
=== Duplicate links ===
Generally, a link to a specific target should only appear once per article, when the relevant word is first mentioned.


Exceptions to this include infoboxes, navboxes, tables, lists and, in some cases, the description of spells or special abilities. In these cases, multiple links per article may be appropriate.
Exceptions to this include infoboxes, navboxes, tables, lists and, in some cases, the description of spells or special abilities. In these cases, multiple links per article may be appropriate.


Sometimes it may also be appropriate to link to a subject introduced at the start of a section, even if the target article has already been linked to previously in that article.
In very long or technical articles, it may sometimes it may also be appropriate to link to a subject introduced at the start of a section, even if the target article has already been linked to previously in that article.


Only use links when they're helpful to the reader – every word that has an article does not need to be linked.
=== What to avoid ===
 
* Do not unnecessarily link to other articles – the mere mention of a word with an article is not reason enough to link to it.
Section headers should never have links in them.
* Do not link to disambiguation pages, except in hatnotes.
* Section headers should never have links in them. Use {{t link|hatnote}} or {{t link|see also}} instead.
* Do not place links immediately next to each other. Either omit one of the links or rephrase the sentence so that the links aren't adjacent.


=== Linking to other wikis ===
=== Linking to other wikis ===
The [[Template:FRWiki|FRWiki]] template should be used to link to the FRWiki when appropriate.
The [[Template:FRWiki|FRWiki]] template should be used to link to the FRWiki when appropriate.


== Templates ==
== Lists and tables ==
Limit usage of unnecessary templates in sentences, such templates that add an icon and a link.
Lists are commonly used on BG3Wiki. Lists can improve presentation and layout, improving readability and make otherwise dense information easier to parse.
 
For paragraphs or flowing text, prose should be used instead.
 
For accessibility reasons, lists should always be used correctly; lists can improve accessibility and readability when used with care and consideration, but when used incorrectly, they can become a hindrance.
 
=== Description lists ===
Description lists are used for lists that consist of names and values, terms and definitions, items and descriptions or questions and answers. They are added using semi-colons and colons:
{{comparison table|example=
<pre>Description list:
; Hit points : Determines how much damage a creature can take before being Downed.
; Armour Class : Determines how difficult it is to hit a creature.</pre>|result=
Description list:
; Hit points : Determines how much damage a creature can take before being Downed.
; Armour Class : Determines how difficult it is to hit a creature}}
 
Description lists can be formatted similarly to a table with {{t link|table list}}:
{{comparison table|example=
<pre>Description table list:
{{table list|
; Hit points : Determines how much damage a creature can take before being Downed.
; Armour Class : Determines how difficult it is to hit a creature.}}</pre>|result=
Description table list:
{{table list|
; Hit points : Determines how much damage a creature can take before being Downed.
; Armour Class : Determines how difficult it is to hit a creature}}}}
 
=== Ordered and unordered lists ===
Ordered and unordered lists can be used to list items.
 
These lists are intended for items that consist largely of names or simple phrases. If a bulleted list item consists of several sentences, it is generally best {{em|not}} to include it on a list, and instead work it into the textual body of the article.
 
; Important considerations
* Only include a full stop at the end of an item if it consists of a full sentence.
* Do not use '''bold''' typeface to format the list – use a description list instead.
* Do not leave blank spaces between items (asterisks or hash symbols), since this breaks the single list into multiple lists.
 
==== Bulleted lists ====
Bulleted lists, or ''unordered lists'', are added using asterisks (*):
{{comparison table|example=
<pre>
List of bulleted items:
* unordered item
* unordered item</pre>|result=
List of bulleted items:
* unordered item
* unordered item}}
 
===== Indented bullets =====
Bulleted list items can be indented using double asterisks:
{{comparison table|example=
<pre>List with indented item:
* unordered item
** indented item</pre>|result=
List with indented item:
* unordered item
** indented item}}
 
==== Numbered lists ====
Numbered lists, or ''ordered lists'' are used where numerical order (arrangement) is important. They are added using hash symbols (#):
{{comparison table|example=
<pre>List with numbered items:
# numbered item
# numbered item</pre>|result=
List with numbered items:
# numbered item
# numbered item}}
 
=== Plain and horizontal lists ===
Plain and horizontal lists are frequently used in templates such as navboxes or infoboxes, but can also be used in article contents.
 
=== Horizontal lists ===
Horizontal lists can be used where a vertical list may be undesirable. They are added simply by listing items in succession, in a single line:
: item 1, item 2, item 3 ...
: or
: item 1 • item 2 • item 3 ...
 
The template {{t link|horizontal list}} can also be used to add horizontal lists:
; Using bulleted lists
{{comparison table|example=
Horizontal bulleted list:
<pre>{{horizontal list|
* item 1
* item 2
}}</pre>|result=
Horizontal bulleted list:
{{horizontal list|
* item 1
* item 2
}}}}
 
; Using description lists
{{comparison table|example=
Horizontal description list:
<pre>{{horizontal list|
; term : definition
; term : definition
}}</pre>|result=
Horizontal description list:
{{horizontal list|
; term : definition
; term : definition
}}}}
 
Nested lists can also be made horizontal this way:
; Using bulleted lists
{{comparison table|example=
Horizontal bulleted list:
<pre>{{horizontal list|
* item 1
** item 2
* item 3
** item 4
}}</pre>|result=
Horizontal bulleted list:
{{horizontal list|
* item 1
** item 2
* item 3
** item 4
}}}}
 
==== Unbulleted lists ====
Unbulleted lists can be added with {{t link|unbulleted list}} template:
{{comparison table|example=
<pre>Unbulleted list:
{{unbulleted list|
* item 1
* item 2}}</pre>|result=
Unbulleted list:
{{unbulleted list|
* item 1
* item 2}}}}
 
== Tables ==
Tables can be useful, but must always be carefully implemented in order to ensure accessibility and usability across a wide variety of devices.
 
This section is about tables used in the bodies of articles, and not about tables implemented as infoboxes or navboxes, which follow separate guidelines.
 
=== Table formatting ===
Table must be formatted correctly on the wiki. Tables should always be 100% width, and should be limited using max-width and, ideally, ems or % instead.
 
==== Headers ====
As with section headers, always use sentence case in table headers.
 
For accessibility reasons, it's important to ensure that headers are properly formatted. Using wikitext, headers are defined with {{code|!}}:
<pre>
{| class="wikitable"
! Header
|-
| Not header
|}
</pre>
 
Which produces:
{| class="wikitable"
! Header
|-
| Not header
|}
 
==== Style ====
Colours used in tables should always be defined via classes implemented through CSS, as opposed to via style parameters
 
=== Table usage ===
Tables on BG3Wiki are used to present complex information and data of tabular nature. Tables are also used on cargo pages and selectively on project and help pages.
 
Tables are should generally only be used when the information cannot otherwise be prevented in the form of a list.
 
Tables should {{em|not}} be used simply for visual reasons, such as for layout or presentation.
 
==== Examples of correct table usage ====
{| class="wikitable"
! Character !! Race !! Class
|-
! Astarion
| High-elf || Rogue
|-
! Karlach
| Tiefling || Barbadian
|-
! Gale
| Human || Wizard
|-
|}
 
{| class="wikitable"
|+ Odds of landing on a target number when rolling a d20.
! Target !! Ordinary chance !! Advantage !! Disadvantage
|-
! 1
| 5% || 0.25% || 9.75%
|-
! 10
| 5% || 5.25% || 4.75%
|-
! 20
| 5% || 9.75% || 0.25%
|-
|}
 
{| class="wikitable"
! Item !! Description !! Location
|-
! Longsword
| Can cast a spell. || Found in this location.
|-
! Greatsword
| Can cast two spells. || Found in this location.
|-
! Dagger
| Cannot cast spells. || Found in this location.
|-
|}
 
==== Examples of incorrect table usage ====
{| class="wikitable"
! Act !! Expected level
|-
! Act One
| 1-4
|-
! Act Two
| 5-8
|-
! Act Three
| 9-12
|-
|}
 
{| class="wikitable"
! Action !! Description
|-
! Attack
| Used to attack a target.
|-
! Hide
| Used to hide from sight.
|-
! Jump
| Used to jump to a location.
|-
|}
 
{| class="wikitable"
! Item !! Location
|-
| Longsword
| Found in this location.
|-
| Greatsword
| Found in this location.
|-
| Dagger
| Found in this location.
|-
|}
 
== Icons ==
Icons accompanying a term or link, commonly used via templates on BG3Wiki, should be used when they serve an important illustrative purpose, or serve as a visual aid to improve readability, such as under the following circumstances:
* When a term is used as a keyword or in a list, as opposed to in a full sentence.
* When used in a table, and the icon improves the readability of the table.
 
Icons should {{em|never}} be used in section headers.
 
=== Icons in sentences ===
* {{em|Do not}} use icons in flowing text or full sentences.
** Icons can be used at the start of flowing text (such as before the first word of a paragraph or immediately before the word it is describing) the first time a term is mentioned in an article, and the icon serves an important illustrative purpose.
** Some icons, primarily those readily identified by an icon (such as conditions and features) can be used in full sentences of technical descriptions of item, action or feature properties when they serve as a useful visual cue to the reader. Repeat icons may be acceptable in this case.
 
=== Icon frequency ===
* Avoid overuse of icons, particularly in already icon dense paragraphs.
* Do not unnecessarily repeat icons.
* Do not introduce a term with an icon multiple times in an article.
 
== Spoiler and content warnings ==
BG3Wiki employs the use of spoiler and content warnings at the top of articles or sections.


If adding an inline template would violate the capitalisation or linking guidelines if added, it should usually not be used.
For the purposes of articles this wiki, excluding the main page, the following is considered a spoiler:
* Plot development and story beats of the main narrative of the game.
* Scripted character deaths in any act, including deaths outside of player control.


=== Spoiler and content warnings ===
=== Spoiler warnings ===
{{hatnote|See also: [[Help: Spoiler policy]] and [[Help:Content warnings]].}}
When creating an article that includes spoilers, you should add a {{tlink|spoiler warning}} to the top of the page or section, if no spoilers appear above that section in the article.
Spoiler and content warnings should be used in accordance with the [[Help: Spoiler Policy|Spoiler Policy]] and the [[Help:Content warnings|Content Warning Policy]]. Ideally, they should not disrupt the user experience, but should effectively warn the user of spoilers and sensitive topics.
<pre>{{SpoilerWarning|act=1}}</pre>
{{SpoilerWarning|act=1}}
Specify which act the spoiler applies to, per the example. For recurring characters who appear in more than one act, it may make more sense to use the general act-agnostic spoiler warning:
<pre>{{SpoilerWarning}}</pre>
{{SpoilerWarning}}


==== Spoiler and content warning templates ====
Spoiler andcontent warnings should be used in accordance with the [[Help: Spoiler Policy|Spoiler Policy]] and the [[Help:Content warnings|Content Warning Policy]]. Ideally, they should not disrupt the user experience, but should effectively warn the user of spoilers and sensitive topics.
* '''Spoiler warnings'''
** [[Template: SpoilerWarning]]: Provides guidance to viewers on what part of the game they may expect to be spoiled on if they read the articles.
** [[Template: SpoilerBox]]: Intended for sections with major spoilers.
** [[Template: RomanceBox]]: Intended for the Romance sections of articles, including Romance encounters with non-companions.
** [[Template: Blur]]: Intended for inline spoilers in NavBoxes and, rarely, in lists.
** [[Template: imgblur]]: Intended for spoilery images.
* '''Content warnings'''
** [[Template: Cw]]: Used exclusively for content earnings.


=== Creating a new page ===
=== Content warnings ===
When creating a new page, whenever possible, try and use a [[Help:Template_Quick_Reference|Page Creation Template]].
Content warnings are indicated with {{tlink|cw}}.
Retrieved from "https://bg3.wiki/wiki/Special:MobileDiff/128929...160505"

Navigation menu