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 Planets.nu 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.

Content

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:

• Descriptions should be clear and concise. No extraneous text should exist in pages that are designed to describe the working of the interface.
  • All processes normal to the game are documented.
  • Exceptions to these normal processes are documented.
  • We do not document non-exceptions to the normal processes. (It's not our job to think for people.)
• Humor is an intrinsic part of the Planets tradition, since the original game was designed to spoof many existing popular science fiction universes. This humor should exist throughout the documentation wherever appropriate. It should never be overtly offensive; specifically, one should never refer to the Fascists as "Germans" or "Nazis"; however, a casual reference to the "brown-shirted Fascist ground troops" (less acceptable - some nations use brown uniforms) or "jackboots" (more acceptable) is less overt and would cause little offense in the present world climate (which is subject to change, as should be the documents). The ideal, however, is exemplified in the placement of the Amorphous soup recipe, which is unlikely to offend anyone who isn't an Amorphous life form. The key here is that the humor should be light , and should be phrased to not offend the potential reader and not infringe on the Copyrights of others. NOTE: Humor of a sexual nature has no place here . Neither does humor at the expense of any person who is not a public figure, or inappropriate humor at the expense of any person or group of people.
• People come here looking for facts, not opinion. Only in the Guides and Contributions sections is the subjective truly appropriate, and even then it is not ideal content for official documentation. However, since we lack any true knowledge of the working of the Host, the only intelligence we have for such aspects of the game must necessarily be subjective -- and that's half the game. As such, some speculation is essential for the documentation to be truly informative. It should be kept formal and professional in tone.
• Professional writing does not mean the same thing as "boring writing." Boring writing should be avoided whenever possible. Add humor; if you can't be funny on your own, perform this mental exercise: Imagine a funny person, and then ask yourself: "What would he do?"
• Short speech is powerful. We should err on the side of brevity whenever practicable. As evidence, I'd like to offer that the second sentence in this paragraph is long and boring relative to the first, and that this third verges on incomprehensible. Any such writing ought to be eliminated wherever it can be done without drastically reducing clarity.
• I advise every writer and editor in my acquaintance to own and know three books:
  1. "The Elements of Style", Strunk & White
  2. "On Writing", Stephen King
  3. Any elementary-school grammar book has a reference to usage and parts of speech. Ignore anything that has to do with diagramming a sentence or other useless exercises, but keep that usage list open.
  If you need any of these and cannot find them, please feel free to contact Gnerphk directly.

Style

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)

Back