BattleMaster Wiki:Style Guide

From BattleMaster Wiki
Jump to: navigation, search

Basics

  • Use Wiki syntax wherever possible, only use HTML if necessary.
  • Use Templates if (and only if) the same text will appear on at least two pages.
  • Most pages should be in at least one category, define categories always at the bottom of a page
  • Use semantic properties where appropriate, see Semantic Wiki
  • Help pages have a slightly different style policy that should be used.

Guidelines for Personal Pages

  • Please if you create a page about one of your characters, make it a subpage of your family page. For example name the page [[Smith Family/John]], not [[John]]
  • Do not link to your personal pages from official manual pages! The families page does not need links to every family in battlemaster.

Page Name Guidelines

  • Avoid articles (a, an, the) in page names
  • Avoid plurals. Use "Family" instead of "Families" and "Realm" instead of "Realms". This is easy with plural links. Exceptions: If Battlemaster never uses the singular, use the plural. Use "Bonds" not "Bond" and "Taxes" not "Tax".
  • More generally, avoid suffixes. Prefer "deport" to "deportation", use "bank" instead of "banking". Exceptions: use common sense, "banker" is very different from a "bank", "infiltrator" is probably better than "infiltrate" .
  • Links and page names should be plain English and not "CamelCase". MediaWiki does not automatically create links, you have to use the [[name]] syntax, so you can use proper titles as well.
  • Page names should follow the Headline style outlined in the Chicago Manual of Style. The basic rules are:
    • Always capitalize the first and last words, and all major words
    • Lowercase the, a, an
    • Lowercase prepositions (e.g. as, at, for, from, in, plus)
    • Lowercase and, but, for, or, nor
  • Links embedded in running text, however should use the proper case (usually lowercase). Example: The correct page name is "Style Guide", but a link in normal text should point to the style guide.
  • All examples should end with the word "Example" and should be in the "Examples" category. Examples shall contain absolutely no information that is not available on the main article.

Namespaces

Remember that you can not define new namespaces. They syntax might make you believe you can, but "Example:XXX" only creates a page named so, it does not create an "Example" namespace. To cluster pages, use categories, not namespaces. Namespace is a meta-concept.

The namespaces we use:

  • Main (actually: no prefix) - most pages.
  • Help: For pages that help people getting around the wiki.
  • Meta: Stuff for the editors or people interested in contributing things.
  • BattleMaster Wiki: Pages about the wiki itself such as About or Copyrights

Hierarchies

What you can do is create hierarchies. If you name a page "Something/Subpage" then there will be a link back to "Something" on it. This is called a subpage.

It also has the advantage that from the higher page you can link simply by using "/Subpage".


Disambiguations

Sometimes, two different things have the same name, for example "Sirion" can be either the realm or the region by that name. In that case, make Sirion a disambiguation page and put Sirion (Realm) and Sirion (Region) on their own pages where the title uniquely and clearly identifies the subject. Only use this when you have ambiguity. All regions and realms with unique names should have just their name as the page title.


Section Headers

  • Remember that your section names will automatically be added to the TOC. Therefore, use short section names that outline what the section is about.
  • Follow the same Chicago guidelines for section headers.


Article Structure Guidelines

  • TOC (at the very beginning, because the automatic inserting would put it behind the lead paragraph)
  • Every article starts with an overview or abstract that sums up the content in an easy-to-understand language. The purpose of this introduction is that anyone who wants only a summary does get a full set of information on the subject with no important missing bits. He will lack the details but he knows everything that is important.
  • Use sections and sub-sections to structure the content within an article. Section names should be capitalized Headline style (see above).
  • Every article covers its subject completely, using links to more information if necessary, so that someone going to the XYZ article can find everything about XYZ there, or at least links to it.
  • There should be only one non-template link per page. It should be done sooner than later. The one exception are newspaper articles where the links are per article, not per page. Instead of linking to Perdan 20, Caligus 12, and Fontan 34 times from a page, link to each of those once, sooner than later, in a non-template usage.
  • If you ever wonder if you should split a topic up over several pages or write one long article, err on the side of expanding an article. Long articles are better than multiple short articles.

This example article shows how an article can be structured.


Writing Guidelines

  • Talk to the reader - use "you can..." instead of "one can", for example.
  • While you should use "you", do not use "we" unless that we is a qualified group. e.g. "We, the coders" is fine, but "we" as a generic term isn't.
  • Use one of two styles and stick with it throughout the article:
    • Objective manual style - emotionless, informative, neutral
    • Roleplaying style - like the Introduction, written in first person, direct speech, etc.
  • British spelling is the BattleMaster standard. It is "honour", not "honor", for example. If you write an article, at least try. You are free to correct articles from American to British spelling. Please do not change spelling from British to American!

Formatting Guidelines

  • Use wiki syntax if possible, only use HTML if it is really necessary. For example the wiki double-apostrophe is better than <i> unless it is imperative that the text be italic and nothing else. But, don't use wiki syntax just because it looks better, consistency is more important than beauty, and improving optics via CSS is better than having it hardcoded inline.
  • Avoid changing the font size. Headers should be surrounded by equals signs(==). Other text should be normal size.
  • Do not underline text. If you want to emphasize something, italicise it using two apostrophes (''). There is a reason there is no wiki formatting to underline text. You should never underline non-links on the Internet as it is confusing. Users expect underlined text to be links.

Category Guidelines

  • Create a new category if there are more than 4-5 long articles belonging to a topic. Category names should be short, single words if possible.
  • Make sure there is not already a category they would fit into.
  • If there are many articles in a category (say, more than 50 or so), using sub-categories is strongly suggested.
  • Articles should be in the lowest sub-category, if sub-categories are used. e.g. a unique item should be in Category:Weapon (unique) if it is a weapon, and it should not be in Category:Unique Items
  • Remember that articles can be in multiple categories.
  • Categories are a secondary navigation layer. They do not replace a proper navigational structure and category pages are not a replacement for a properly ordered overview or introduction page.

Deleting Pages

Regular wiki contributors cannot delete pages. This is per normal wiki convention. Do not "blank" pages. (i.e. do not edit a page, delete the contents, and then save it.) If a you want a page deleted then post a request on BattleMaster Wiki:Delete Requests. If you created the page, or if the page is inappropriate for the wiki, then it should be removed in short order. Wiki editors regularly check this page for entries. (We love deleting pages, honest!) If your request for deletion cannot be fulfilled for some reason, then one of the wiki editors will leave a note on your user talk page with an explanation.