Author's Guide

This author's guide describes common style rules to maintain a level of uniformity in all of Thaliak's guides so as to not jar readers when they go from one guide to another. In short: it should not be obvious that a timeline was written by a different contributor when a reader reads it.

While guides that do not meet all of these criteria will not be accepted as-is, it is unreasonable and unrealistic to expect a single author to remember all of these criteria when developing a guide without any slip-ups. Therefore, while an author should attempt to uphold as many of these rules as possible, it is ultimately the submission team's job to find and correct any style rule violations.

(Note that there is a limit to this. It is the submission team's job to find minor mistakes, not to rewrite the entire guide for a contributor. If too many style errors are found during proofing, the submission team may request another revisioning pass from contributors.)

It is strongly recommended to utilize the official Red Hat YAML VSCode Extension alongside our own VSCode extension to find and fix as many errors as possible before you submit your pull request.

Language/Phrasing

• Prefer to use active language rather than passive language.
  Bad example: The status x is inflicted on all DPS.
  Good example: The attack inflicts x on all DPS.
• Prefer to use present tense, not future tense.
  Bad example: [boss] will jump on a random player and...
  Good example: [boss] jumps on a random player and...
• Within an action, status, or timeline item, always describe the effects of the mechanic, not what players should do in response. Describe how players should handle mechanics in the resolve or strategies sections.
  Bad example: Pile Pyre requires players to stack with someone of the opposite role.
  Good example: Pile Pyre deals heavy damage to all players of one role. Stacking reduces the damage to survivable levels.
• Within a strategy description, use imperative instead of qualifying language.
  Bad example: Players should check the side of the cleave, then move to the opposite side.
  Good example: Check the side of the cleave, then move to the opposite side.

Wording

Instead of	Use this	Context
to do/inflict damage	to deal damage	Damage is dealt to players or enemies.
to apply a status effect	to inflict a status effect	A harmful status takes effect.
to apply a status effect	to grant a status effect	A beneficial status takes effect.
little, medium, a lot of	minimal, mild, moderate, heavy, massive, lethal	Amount of damage dealt by an attack. Don't specify exact damage values in descriptions unless the attack always deals a fixed amount of damage. (That's what the damage property is for.)
character, party member	player
to down, KO, incapacitate	kill, death	When referring to players' or enemies' HP being reduced to 0.
to make	to render	Primarily when referring to the effect of statuses, e.g. Renders any damage taken lethal.
affected players	afflicted players	Referring to players under the effect of a harmful status effect.

Structure

Description

• The description of an action should solely describe how the action works. Any hints on how to resolve a mechanic or concrete strategies should be placed within the resolve or strategies fields.
• The first line of an action's description should be relatively short, to ensure that there is no line wrapping for this timeline item on a medium-sized display when the timeline item is collapsed.
• When referring to other actions or status effects, always link to them using [a:KEY] or [s:KEY].
• If you use a term matching an item within mechanic-shapes.yaml, mechanic-types.yaml, status-types.yaml, or terms.yaml, always use a tooltip link using [ms:KEY], [m:KEY], [st:KEY], or [t:KEY], respectively, unless you've already used a tooltip for that term within the same property.
• If you're unsure about a specific detail and are unable to verify it in-game, either ask someone for help or put that piece of text within a :unverified(TEXT) tag.
• While some mechanics may have complex conditions on where things can spawn, move, or otherwise deal damage, always try to describe things in the simplest possible manner that doesn't omit any important details.

Strategies (Diagrams)

• Prefer to always add a diagram under graphing when adding a new strategy, unless such a diagram would not add significant value.
• When adding a diagram for a mechanic only has one way to be reasonably resolved, add a single strategy named "Example" and describe the strategy within resolve. You can also add multiple strategies named "Example 1", "Example 2", and so on, if multiple examples (using the same strategy!) would add significant value.

Links

• Use link: or when the boss may use either one attack or another, but not both.
• Use link: and when the boss uses both attacks at the exact same time.
• Use link: then when the boss uses both attacks in rapid succession.
• Use children: ... when some parent mechanic begins a sequence of logically related child mechanics that should not stand alone.