Difference between revisions of "BattleMaster Wiki:Style Guide"

From BattleMaster Wiki
Jump to navigation Jump to search
(added more text begging people to use subpages)
(→‎Formatting Guidelines: made a few changes, mainly underlining is bad on the www)
Line 61: Line 61:
  
 
== Formatting Guidelines ==
 
== Formatting Guidelines ==
* Use wiki syntax if possible, only use HTML if it is really necessary. 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.
+
* Use wiki syntax if possible, only use HTML if it is really necessary. For example the wiki double-apostrophe is better than <tt>&lt;i&gt;</tt> 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.
* Use logical formatting - <tt>&lt;small&gt;</tt> is better than <tt>&lt;FONT SIZE=-1&gt;</tt> and the wiki double-apostrophe is better than <tt>&lt;i&gt;</tt> unless it is imperative that the text be italic and nothing else.
+
* Avoid changing the font size. Headers should be surrounded by equals signs(<nowiki>==</nowiki>). Other text should be normal size.
 
+
* Do ''not'' <u>underline</u> text. If you want to emphasize something, italicise it using two apostrophes (<nowiki>''</nowiki>). 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 ==
 
== Category Guidelines ==

Revision as of 14:17, 29 July 2006

Basics

  • Use Wiki syntax wherever possible, only use HTML if necessary.
  • Make sure to use subpages whenever possible. A page about the "Red bricks of Batesaor" should be called Batesaor/Red Bricks. Or better yet, put it on the same page as everything else.
  • 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

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".


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.
  • 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.
  • 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.