Wiki Editing Guidelines

Guidlines for writing/editing a Swarm Cycle Wiki Article

(This page is currently just ZM's opinions, none of them hold any sort of authority.  That comes from the consensus of the collective Swarm Cycle authors, generated on the email list, with TH as always holding a veto.  Still, until I get further guidance, this is how _I'm_ doing it. ZM User (talk) 08:46, 22 April 2024 (PDT))

Article Name Conventions

   While acronyms are easy to say and easy to type, they are frequently not recognized except by 'insiders'.  Because of this, we tend to have articles named "Fighting Vehicles" instead of "AFVs".  We do allow exceptions for acronyms that are so prevalent that everyone should recognize them.  Everyone knows what "DECO" is.  Who knows what the hell "The Directorate of Evacuation and Colonial Operations" is?  Similarly, we have "FTL" instead of "Faster Than Light" and "CAP" instead of "Capacity Aptitude and Potential".
   Capitalization is important.  Wikimedia is case-sensitive for several things including article/category/template names.  In the past we have had multiple articles "CAP", "Cap", "cap", and "Capacity Aptitude and Potential".  Because of this, we try to capitalize the first letter of words in article names ("Fighting Vehicles", not "fighting vehicles" or "Fighting vehicles"), and we capitalize ALL letters in acronyms.

Readability

   Normal English text is written one way.  HTML adds a bunch of formatting options.  Wiki Markup modifies HTML, both adding and deleting options.  Things get confusing fast when editing a wiki article!

Link Usage

   HTML and Wiki Markup allow special codes that let you click on a word or phrase and have your browser send you somewhere else.  Generally, if your browser can see that the link works, it will be in blue.  If your browser can't find the link's target, it is in red.  On the one hand, that's pretty helpful info.
   On the other hand, we grew up reading black letters on white paper.  A lot of modern devices also support "Dark Mode" which shows you a black screen with white letters.  If you are used to reading, either are fairly easy on your eyes and brain.  Adding those colors adds value, but it also makes it hard for our subconscious to find the letters, words, and meaning behind all those pixels on the screen.

• DO add links where they will add value.
• DO NOT add links where all they do is add color.

(I just got done editing an article that had Confederacy as a link every time the word was used, five times in the first paragraph.  If the reader didn't care enough to click on it the first time, all you are doing is giving him a headache all those other times. -ZM)
   While we're at it, the normal usage is [[DECO]] .  This will display "DECO", and if you click on it it will send you to the article of the same name.  You can also have the target different from what it displays.  [[Hell|Heaven]] will say "Heaven" but it will send you to "Hell".
   Something that is legal but pointless is to do [[DECO|DECO]] .  A reader won't see anything out of the ordinary, but anyone editing that page can't help but question the sanity of whoever typed that.  Still, it's harmless, right?  Why make a fuss?
   Yeah, but consider this link I keep seeing in all those long lists of "These are all the pages that reference this subject": [[We Few, We Happy Few, We Band of Brothers|We Few, We Happy Few, We Band of Brothers]] by [[LughIldanach|LughIldanach]] .
   It's harmless, but... Stuff like that just makes the text and embedded codes harder to read.  Which is important, when you are having trouble finding that broken code that's keeping the page from displaying right.  The bottom line is "Don't type something that adds no value, just to practice your typing."

Spaces

   I have a strong preference for 'traditional' written English format.  That means that every paragraph starts out with THREE spaces, and every sentence is separated from the one before it by TWO spaces.  You know, like this short article.  And every newspaper, magazine, and book you've ever read.  If you do both of those and then only use ONE space between words, it is easy to tell when one sentence ends and another begins, even if the punctuation gets screwed up during an edit.
   This is a publishing 'standard' because it makes reading easier.  Less effort trying to pick out the paragraphs and sentences means more brainpower available to try to absorb the content instead of trying to FIND the content.  The end result is that you don't get a headache after a while like you do trying to read minimal HTML.
   "Minimal HTML" was created back in the late 1970s when both storage and bandwidth were limited.  Because of this, minimal HTML deletes all line-leading 'white-space' and compresses all white-space anywhere else into one space.  Don't save them, don't transfer them, and don't show them.
   Many websites (SOL and standard wikis in particular) still enforce this.  Thus, if you want that space to make it easier to read, you have to tell the software that you want it left alone.  The standard way to do this in HTML is to use a code that this wiki version insists (of course) on converting into a blank space, so I can't show it here except by spacing out each character:   &   n   b   s   p   ;
   To people who grew up in the dark ages, that translates to "start special code, Non-Breaking SPace, end special code".  I just type the characters once, then <CTRL>-C and I paste it in whenever I need it while typing.  After a while it becomes just part of your typing like capitalizing the first word of every sentence, and it makes your text a LOT easier to read.
   Okay, end of sermon.  I can't make everyone else do it, but I'm certainly going to.

Lists

   When typing in a group of similar items like your 'Also See" section, consider using a "list".  Wiki markup considers a line which begins with an asterisk "*" to be a "bullet" item, a separate line in a list.  It requires no other formatting and indeed will ignore a lot of HTML and WML codes.
   If, when you build your list, you put a space after the asterisk, the wiki software will ignore it.  That space won't be seen in the final article.  It will, however, make it easier for the writer/editor to look at it while the page is being worked on.

Article Sections

   Most articles will have some sort of preface before you get to the desired content.  You know, like the warning in bold at the top of this one.
   Wiki software supports an 'outline' structure, and when people are going to a wiki to find things, it helps if things are always organized the same way.  If you are creating a new page for a new infantry weapon, look at the pages that already exist for other weapons and organize yours like them.
   We collect all the (unseen) 'category' declarations at the very bottom of the page, and then put the 'navigation' template call right above them, since that's where we want to see it anyway. If you click on the 'edit' button at the top of this page you'll see all the codes that make this happen.

Speling and Gramer

   This Wiki is produced in Standard English.  That's a problem, because English is spoken and written by many different social groups, and each one has its own version of proper word usage, grammar and spelling.  All articles in the Swarm Wiki should adhere to American/USA usage.  Examples include color, a car's trunk, a truck, specialization, organization.
   The exception to this rule is any article about a British Commonwealth subject.  Stories about Canada, the UK, Australia, or colonies or ships manned by people from the Commonwealth should adhere to standard British usage.  Examples include colour, a car's boot, a lorrie, specialisation, organisation.
   Let's add 'tense' to the list of writing issues.  English has three main tenses: past, present, and future.  Consider the following sentence: "Pern is in the Rukbat system and is Earthlike in that it had a molten iron core and an atmosphere roughly analogous to that of Earth with slightly higher oxygen."  Now that we've read that sentence, we know where Pern _is_ and what it _is_ like and that it once _had_ something important.
   What happened to that molten iron core?  I suspect that the writer forgot he was writing in present tense and should have said "...it has a molten iron core..."  Editors should take care to stay in PRESENT tense when talking about something that exists now, in PAST tense when talking about something that used to exist, and FUTURE tense when talking about something that may happen in the future.

Test Page

   This wiki has a test page at Wiki Test Page.  This page is there for me and other editors to try things out and see how they work.  And how they look.  The top section shows how to set up several common formatting options and how they look in the finished page.  At the bottom is a free test area for editors to try things in.
   We also have a "template" page at Blank Formatted Article.  You can open that up for editing and copy the raw code into your new article to help you make your article look like the others.  What you CAN'T do is mess up that template article by acidentally saving your work in the template, because it is write-protected.

(Someday this will be a navigation template.  It will provide a bar across the bottom of each article with useful navigation links.  Until then, this is just a placeholder to get rid of all the red "broken link" indicators. -ZM User (talk) 10:00, 3 May 2024 (PDT))