User Tools

Site Tools


wiki:style_guide

Crossfire Wiki Style Guide

Some information about “how to style pages” - for consistency.
NO, you won't be banned for breaking these.

Structure

The following information discussed the overall structure and implementation of the Wiki pages.

A couple of very general points about the Wiki:

  • It is important that the wiki (and crossfire website) be maintained so that information is easy to find.
  • Where possible, information that belongs on the crossfire website should not be duplicated on the Wiki.
  • Information should probably be minimised on the website to maximise the value of search hits and the search function on the wiki.

The new structure for the wiki is split into 4 sections:

Mechanics

The Sworn book of Scorn - mechanics - includes all aspects of game play such as map data, arc data and in game features and formulas that affect players. This includes

The Sworn Book of Scorn section was created by saru and feedback can be directed to him. Every attempt to incorporate existing information neatly into this section has been made, however, there are still vast areas that require completing. The orphans_and_missing page is an excellent place to find pages that need more information.

Why do we need it?

“But all this information should be available in game, players should just play more.”

Whilst it is true that Crossfire should provide players with all the information they need to understand and succeed, for a variety of reasons this is not always the case:

  • Some players will not be playing on large servers, and, may never interact with others in the crossfire world. Many things that experienced players take for granted was gifted to them as they were learning by more experienced players. It is not fun to get completely stumped by something in game because it isn't well explained. Providing the information here levels the experience.
  • Players may not be fluent in English, these pages are much easier to translate
  • Fixing the problem in-game can be much more daunting for new developers than simply documenting them on a wiki.
  • The Crossfire Wiki also acts as a tool to identify information that is not clear in game by using page analytics. Large numbers of hits to particular parts of the wiki can be a sign that more information or tweaks are required in order for new players to understand mechanics better. The development team reads changes to this wiki and can consider adding information to the game during the development cycle.
  • Development usually starts with “getting something to work”, before documenting it, and often well before providing clues on how it works in game. Unfortunately this leaves many parts of the game in various states of completion and sometimes left uncompleted before the developer moves on to greener pastures. Whilst this might not be the best approach for game design (large organisations regularly get grilled for such failures), it is important to remember that Crossfire is created entirely by volunteers for fun. Having a wiki pages to work from often helps speed up implementation.
  • Many well designed and intuitive games still have wiki pages built by fans that are very popular. They are a great means of reaching out to new players by providing a more accessible means of information for players if they want it. If you don't want any help, just don't read the wiki pages.

Spoilers

Some of these pages can be considered spoilers and there is a fine line between explaining how something works and giving something away. Avoiding including spoilers in The Sworn book of Scorn can best be avoided by:

Avoid long pages filled with “everything you ever needed to know about blah” Instead split information up into very specific pieces. Put a summary paragraph at the top explaining what readers will learn from that page. In this manner players can search for the particular information they are stuck on (for example, what is my damage not going up when I increase DEX, what does this monster seem to never die when I cast this spell at it) without stumbling upon things they didn't intend to read.
Do not include specific advice about maps or scenarios Avoid giving away the game by including information that was never intended to be revealed in game unless there is no other way around it. For example, do not explain that the secret key to get into the room filled with wonderful treasure is hiding under a bush at coordinates x and y.
Stick to the facts Do not provide opinion such as 'this item is regarded as the best' or 'this map is rarely visited because it is hard and has little reward'. The place for opinion and guidance is in the guides section of help/Support

Help/Support

This section is for all information that helps new players get access to and learn how to play crossfire. Some tips for adding information to this section:

  • There is a grey area between system support and in game support that the player probably wont even notice. For example “my client doesn't work because I can't get through the gates out of scorn” is actually a server bug related to the python plugging not loading. Therefore create as many cross references between help articles to allow new players to find what they are looking for.
  • Try to avoid being too technical about how the game, server, and client work. Only give relevant information to get the player going on their merry way.
  • Avoid putting commentary in here such as FIXME this section needs lots of work. Players coming to these sections are looking for help, not to give it!
  • If the information is out of date, just delete it. If you really want to hang on to it, dump it in development or let it be orphaned.

FAQ

This document is a one size fits all go to for common questions. This is also often a first touch point for visitors so care in making sure the information is accurate and relevant is critical. Wherever possible link to other sections of the help/support section to provide more detailed answers if it is possible they may need it. Thought should go into why things are in the FAQ (e.g. problems that can't be avoided such as operating system bugs) and this document should be kept as short as possible.

Downloads

This probably should directly link to the crossfire website.

Client

All information related to supporting players get their particular client running on their particular system. For example platform specific advice can be given here.

Server

All information related to supporting players get their servers running. It should be noted that the general preference is to put newer players onto an existing server before attempting to run their own.

Player Guides

Anything related to getting players up and running in game belongs in here. There really shouldn't be guides in here explaining how to level fast or become super powerful, isn't that the fun part of working out Crossfire for yourself?

Community

Crossfire is a fun project to play and develop. These are pages to convey this.

Development

Dev - These pages are focused on development in crossfire. Developers be Here, This is the wilds, enter at your own risk!

General Style Guides

Lists

Generally speaking, any time a list of steps or content needs to be followed in a specific order - use a ordered (numbered, alphabetized, etc. list)

Ex:

  1. Launch your browser
  2. Click on File
  3. Click on Print

Anytime the context can be taken out of order and still make logical sense, use an unorderd list or bullet points.

Ex:

  • Humans
  • Elves
  • Troll

This is based off the Docbook guidelines, http://i18n.kde.org/docs/markup/lists.html

Naming pages that are about maps

If a page is about a certain map, the page should be located within a namespace named after the region(s) the map is located in. This should prevent confusion if two maps are similarly named, as an example: dragon guild in Scorn (/scorn/misc/dragon_guild) and the dragon guild in Navar (/navar_city/misc/dragon_guild).

For Example:

  • world:pupland - a page about pupland
  • world:pupland:lone_town - a page about Lone Town
  • world:pupland:lone_town:SOMEMAP - a map in Lone Town

If a map is part of a dungeon (or similarly sized map set), please try to keep everything about the dungeon (or map set) on one page.

Media

  • When adding media, try to add new files to mirror the structure of the wiki page in general (e.g. images related to monsters belong in monsters)
  • Only use images in user folders, on user pages.
  • Avoid doubling up, if you want to use an image out of context, go to the folder where it would be in context. (e.g. if you use a monster image as part of a to do list, take the image from :monster rather than uploading another copy).
  • If an images has come from the archetypes, leave it as the original file name.
  • If an image isn't from the Archetypes, name it as clearly as possible.
wiki/style_guide.txt · Last modified: 2018/03/27 09:09 by karl