VGA Planets


How The Website Works






General Information



Searchable Documentation

Editorial Guidelines

Administrative Interface —> Editorial Guidelines

NOTE: This is a living document, and is subject to change. With that in mind, it should never be changed without discussion.

This document is intended to provide general direction for content and style within the documentation. The rules and guidelines expressed within are, like the Documentation Standards, to be considered "strong guidelines" rather than hard and fast rules; but care should be taken to adhere to them whenever practicable.

There's a reason that internal consistency is a high ideal across many industries, and that reason is a simple one: Consistency makes documentation easier to understand. This documentation exists to educate the users; if the users are confused by the format, it becomes less likely that they will gain the intended benefit. In extreme cases, it's better to have no documentation than confusing or erratic documentation. (Likewise, consistency in internal style makes documentation easier to edit; hence the Standards page.)

Readability, accuracy, precision, and consistency are our four ideals, in that order. Readability trumps every other virtue in that, if a document cannot be understood by the reader, it is useless no matter how accurate it is. Accuracy is always more important than precision -- except on charts and tables, where each has its equal place. Consistency is vital, but any of the other three ideals are more important: one instance of this is in the avoidance of repetition in order to improve readability.


This is documentation. The primary goal of documentation is to inform the user, and all rules are subordinate to this ideal within the limits of the practicable. "Inordinate difficulty to create or maintain" makes something impracticable; so does "This violates copyright" or "The developer doesn't want us to answer this question". When in doubt, err on the side of professionalism. When practicable, err on the side of elegance.

There are several distinct sections to the game documentation, and each has an appropriate tone and format. It is important that these remain internally consistent within each section in order to promote readability. The following are general rules for content that should be applied with more or less rigor depending on the section, as appropriate:


I'm going to make a couple of quick style suggestions. By "style", I mean methods of formatting, grammar, and punctuation. By "suggestion", I mean, "My way is right and proper, and any other way is wrong". However, I'm being polite about it, so it's all good. And by "quick", I'm just plain lying.

  1. We adopt the Americanized spelling of most terms. One exception that informs the rule: The plural of "torpedo" is "torpedoes" in most classic military publications, and this should be our guide.
  2. We use standard proper grammar in most cases, but err on the side of clarity when usage permits. Specifically, this permits the use of the so-called "Oxford Comma" in comma-delimited lists.
  3. We maintain the spelling errors in the game as long as they remain misspelled within the game. This includes the "Gaurdian Class Destroyer" (all three versions). We can fix them later -- once the game has been altered.
  4. We take great care with abbreviations to ensure clarity. One instance of this would be the ambiguous "FC", which could mean either "Friendly Code" or "Firecloud", and has even in the past be used to represent "Falcon". I'd like to suggest that, where ambiguity is possible, we should avoid an abbreviation entirely. The only abbreviations that are commonly accepted are:
    • dur —> Duranium
    • KT —> Kiloton
    • moly —> Molybdenum
    • tri —> Tritanium
    Specifically, "ly" is not accepted as an abbreviation for light-year. While technically correct, it introduces potential ambiguity. As a general rule, all abbreviations should be avoided unless they improve clarity.
  5. In the English language, generally, adjectives are ordered thus:
    1. Quantity
    2. Quality
    3. Size
    4. Age
    5. Shape
    6. Color
    7. Proper adjective
    8. Purpose or qualifier
  6. Proper word usage and spelling are vital. Attention should be paid to usage, particularly for difficult terms such as "affect" versus "effect" and other homonyms. (See this external link for an example.)
  7. Excessive repetition of a major word within a sentence or even paragraph is to be avoided when practicable. Ships can be called starships, vessels, warships and freighters (these last two would limit the effected starships). Employ variety when you can. Exceptions are, as always, made for clarity; we consistently say "ship limit" rather than "starship limit", "shipbuilding" instead of "starshipbuilding", and "ship-to-ship" is always better than "vessel-to-starship".

With regard to the work "The Elements Of Style", I would like to provide a couple of quotations:

Rule Seventeen: Omit Needless Words

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short or avoid all detail and treat subjects only in outline, but that every word tell.

This also is of great value:

It is an old observation that the best writers sometimes disregard the rules of rhetoric. When they do so, however, the reader will usually find in the sentence some compensating merit, attained at the cost of the violation. Unless he is certain of doing as well, he will probably do best to follow the rules.

Wm. Strunk (as quoted in White's Introduction)