Style guide

From WikiRPS

Originality is encouraged, yet everyone benefits from some reasonable consistency. These principles should be considered guidelines, not hard and fast rules. If you think any of these guidelines are just plain wrong, please make your suggestions on the talk page.

[edit] Title format

[edit] Singular

Page titles should be in the singular whenever possible. This facilitates the use of links without redundant redirects.

[edit] Capitalization

We (try to) follow Wikipedia's practice with titles and section headers, capitalizing the first letter only (and proper names, of course). This eliminates most of the need for redundant redirects.

[edit] Parentheses

Parentheses in titles should be used only to differentiate different variants of the same rule. The basic version of the rule (or standard version if there is no basic version) should not use parentheses. See feature variants as an example.

[edit] Sections and headings

See Wikipedia's discussion.

[edit] Title section

The title of a page can be reiterated when helpful, using L1 (one equal sign). This is often useful when the page has an intuitive title which is different from its formal name (see moderate skill difficulty) or when including category information (see longbow).

L1 (one equal sign) should only be used for a page title. (Exception: Listing variants.)

[edit] Subsections

Use section and subsection headers generously, as they provide quick and easy indexing, as well as making the page easier to read. Contrast boldface markup, which mimics the appearance of subsections, but does not provide the indexing.

Unless you have a compelling reason to do otherwise, start sections at L2 (two equal signs), and don't skip levels for subsections.

[edit] Definitions

Use boldface to identify jargon terms being introduced and defined. A term should only be in bold once, at the point it is introduced.

[edit] Links

[edit] Internal links

If you reference a jargon term, link to its definition the first time you use it.

If you reference a jargon term that hasn't been defined yet, go ahead and link it anyway. The broken link will serve as a reminder, and eventually it won't be broken any more.

Make extensive use of the pipe trick to save typing and avoid mistakes.

[edit] Redirects

A redirect for a common term (e.g. skill) can save lots of work down the road, since folks can just link the term without needing to remember the precise page name. It's also handy if the page gets moved later on, since you just have to edit the redirect once instead of every individual link.

[edit] Disambiguation

In general, redirects only work for unambiguous terms. For instance, if shield refers to a skill, a spell, and an item of equipment, then you probably can't use a redirect. Instead, it can be helpful to offer a disambiguation page.

When possible, try to avoid ambiguous terms. Otherwise, use a descriptor in parentheses, e.g. dodge (action) vs. dodge (skill).

[edit] Interwiki links

Many concepts we refer to are discussed in detail on Wikipedia, e.g. role-playing game. Make the link. Unusual terms might also be linked on Wiktionary or some other interwiki site.

[edit] External links

As a rule of thumb, if a Wikipedia article is available for a subject, it's better to link that than some other website. A common exception is for commercial products, when it seems appropriate to send folks to their own website, e.g. GURPS. Feel free to use external links as appropriate.

[edit] Categories

[edit] Category items

Any topic that implies a class of items should be created as a category. Information about the category, itself, can be included in the editable portion.

[edit] Category tags

Each page should generally have one or more "is a" category tags indicating where it fits in the conceptual hierarchy, e.g. [[Category:Boon]].

Each non-category rule or documentation page should include one or more "is in" module tags, e.g. [[Category:Core]]. Category pages should not have module tags.

Each rule page may also have one or more complexity tags, e.g. [[Category:Basic]]. This is important when alternative variants exist for different complexity levels.

In general, a page should not include a category which is a supercategory of another tag. For instance, if you use [[Category:Attack, weapon]], you should not also use [[Category:Attack]].

[edit] DPL

See DPL.

[edit] Variants

In general, we want to offer a "stealth to wealth" approach where variant options are available for those who want them, but they don't confuse the newbie who's just trying to get a handle on the basics. This should be the guiding principle when formulating and presenting variant rules.

[edit] Complexity

See discussion under computation.

[edit] Listing variants

Variants of the same rule can be laid out either as multiple pages or as multiple sections of the same page. If the changes are comparatively simple and supplement one another, e.g. in a basic-standard-advanced progression, it may be easiest to display them on the same page, with each variant under a new L1 header to make them stand out. This is an exception to the prohibition against L1 headers.

If the changes are complicated, and/or replace one another, e.g. flat-shallow-steep-hybrid, it may be easier to represent them on separate pages, each containing an L2 Variants section pointing to the other alternatives. Relevant sections should be copied to each page (possibly with a template), rather than making the reader go back and forth.

For examples of the two approaches, see: