Difference between revisions of "Help:Editing guidelines"

Revision as of 00:24, 6 February 2014

Here's some general editing guidelines that you should keep in mind when editing the Mushpedia.

Note: This guide is still under construction and will gradually be expanded. It's advisable to put this article on your watchlist to keep track of new additions.

Note: Many sections here were adapted from the excellent Dota 2 Wiki's Style guide.

General ideas

• While it's awesome and preferable that editors follow all the instructions below, adding raw, unformatted and "messy" information (as long as it's correct) to the wiki is better than not adding anything at all! If you have something to contribute, don't be afraid that it might be rejected. At the moment of writing, the wiki has certain people who are more than happy to add "polish" to raw data... as long as there IS something to work with!
• Your vision of the wiki - or an article - may differ from other users'. Try to find a compromise and not create/take offense involving changes! Mushpedia is a cooperative effort, not a competitive one.

• If there's a feature you think the wiki is missing, for example if there's no template for status icons yet, you're free to try and implement it yourself, or at least request it!
  • However, there are limits. A rule of thumb is to work with what the wiki gives you; some features or changes may either be long present, unnecessary, or unwanted (see the Tables point under Appearance). Never be afraid to communicate and ask (just like in Mush!) before making big changes.

• Mushpedia is a wiki encyclopedia. The purpose of articles on a wiki is to provide all information on the subject in a structured fashion. While tutorials, tips and advice are within the scope of an article, typically articles aren't just that.
  • Example: Instead of creating a "Gardening" article to paste Rain's gardening guide tips&tricks into it, try to also fill the article with general information; what Gardening is, its mechanics, what Skills and NERON Projects are related to Gardening etc. Advice, good gardening practice etc is just one section of the article.

Introduction

The introduction of a Mushpedia article is the section before the first heading. The table of contents, if displayed, appears between the lead section and the first headline, or to the right.

The lead should be capable of standing alone as a concise overview of the article, briefly describing its most important points. It should contain up to four paragraphs and should be written in a clear, accessible style so as to invite a reading of the full article.

The article's subject should be mentioned at the earliest natural point in the prose in the first sentence, and should appear in boldface. For example:

The heart and soul of your character, Skills determine your unique powers and abilities in Mush.

General writing style

Articles should be written in the third person if possible. While writing on Mushpedia doesn't need to be neutral, you should try to avoid personal reference. Sentences such as "I like to duck behind the boxes because it gives me better cover" could easily be phrased as "Ducking behind the boxes provides better cover".

Formatting functions like bold, italics, and linking are provided to improve readability of articles, so use them (see Wikipedia cheatsheet for additional help). If you wish to emphasize a word, such as a skill or item name, use the appropriate template for the first time in the paragraph, then apply italics rather than bold or CAPITALS. Use of the bold face type should be limited within an article whenever possible to table headersand names of Actions (although names should only be highlighted once per paragraph). Double emphasis should also be avoided but can be used for text such as important warnings by making the word bold italic. Italics and quotation marks are also used in names of pieces of media. For example, game names are italicized.

Do not use

• ALL CAPS
• Instant messenger language abbreviations - R U OK?
• Emoticons - :)
• Excessive punctuation - !!!
• Sentences starting with lowercase - "place the portal in the corner"

Using information from the forums

Mushpedia is an independent source of information. Thus, while you can use information from the Mush forums or other players, please do not just copy/paste information, and do not leave it uncredited. Any submitted content should be your own work, and not that of somebody else; unless you have received full permission to use it.

Overlinking and underlinking

For a complete guide to linking please refer to Wikipedia's Manual of Style (links).

The use of links is a difficult balance between providing the reader enough useful links to allow them to "wander through" articles and excessive linking which can distract them from their reading flow.

Underlinking can cause the reader to become frustrated because questions may arise about the article's contents which can only be resolved by using the search option or other sources for clarification, interrupting and distracting the reader.

Overlinking may distract the reader because links are usually colored differently causing the eye to shift focus constantly. Additionally if the same word is linked multiple times in the same paragraph it can cause the reader to question if the links are directing them to different articles or not.

The guidelines for linking are:

• No more than 10 percent of the words in an article are contained in links.
• Two links should not be next to each other in the text, so that it looks like one link - such as Mush Hunter.
• Links for any single term should not be excessively repeated in the same article. Excessive linking is more than once for the same term, in a line or a paragraph, which will almost certainly appear needlessly on the viewer's screen. Remember, the purpose of links is to direct the reader to a new spot at the point(s) where the reader is most likely to take a temporary detour due to needing more information.
• Duplicating an important link distant from a previous occurrence in an article may well be appropriate. If an important term appears many times in a long article, but is only linked once at the very beginning of the article, it may actually be underlinked. Indeed, readers who jump directly to a subsection of interest must still be able to find a link. But take care in fixing such problems, the distance between duplicate links is an editor's preference, however if in doubt duplicate the term further down the article.

Appearance

• Generally try to work with the tools given to you by the wiki. Use "thumb", "right", "frame" etc. parameters to display images in various positions, use wikitables to display information in a table, etc. etc.
  • Tables: Please use the regular "wikitable" class and avoid customizing as much as possible. Once we have a design for the site, it will be very very easy to do a global css change to make the wikitable format be whatever color/format/etc looks best down the road. I know it's boring now, but I promise we'll make it better!
• Before uploading new images, check Image Gallery as almost every image you'll ever need is listed there.

Templates

Familiarize yourself with our selection of Useful Templates before editing. They go a long way in making an article clearer to read and providing valuable information at a glance. Compare:

Phagocyte heals 4 ap and hp

to

Phagocyte heals 4 and

The second example immediately shows that Phagocyte is a Mush skill and provides a link for more information. Also it displays the proper icons for AP and health points, as well as making them clickable so the reader can find out what these points stand for.

Avoid overusing and underusing templates; the same directions as for links apply. If you've already referred to a skill with the Skill template once in a paragraph, there is no need to do so again; emphasize the name with italic text instead. This will help cut down on icon spam and help maintain readability of articles. Note that this doesn't apply to small icon templates like , , etc, as these should be used consistently.

Bad example

You can turn Standard Ration into Cooked Ration to get rid of bacteria, but even Cooked Ration will eventually spoil and need to be refrozen into Standard Ration.

Good example

You can turn Standard Ration into Cooked Ration to get rid of bacteria, but even Cooked Rations will eventually spoil and need to be refrozen into Standard Rations.

Specific wording

It does not help that Mush has extremely inconsistent style and terminology, but the Mushpedia should still follow a consistent approach. What follows are best guesses and recommendations, and is subject to revision.

Capitalization

Words that should be capitalized

• Mush
• fields of activity: Research, NERON Projects, Astrophysics, Communications
• action properties: Aggressive, Covert, Secret, Public etc
• items: Retro-Fungal Serum, Scrap Metal
• equipment: NERON's Core, Patrol Ship, Astro Terminal
• statuses: Dirty, Broken Hand, Chronic Vertigo
• traits: Immunized, Hyperactive, Germaphobe
• Relay
• Hunter/Hunters

Words that should not be capitalized

TODO: Some of those probably exist!

Words with ambiguous or unknown capitalization

• action
• skill (unless first referring to the Skills article)

Terminology

• Players control characters.
• Characters have skills and levels.
• Characters can pick up and hold items.
• Rooms often have interactive equipment.

Words best avoided

• Neron: Should be NERON.
• Pilgred: Should be PILGRED.

Useful official resources

Since the Mushpedia functions in pretty much the same way as Wikipedia and is based on the same software, a lot of general ideas from Wikipedia's much more extensive, detailed guides also apply here. Check it out!

Overview

• WikiMedia's Page on Starting a Page
• WikiMedia's Page on Advanced Editing

Specifics

• WikiMedia's Page on Wiki Language Commands
• WikiMedia's Page on CSS in a Wiki
• WikiMedia's Page on HTML in a Wiki