ModEnc is currently in Maintenance Mode: Changes could occur at any given moment, without advance warning.

ModEnc:Styleguide

From ModEnc
Jump to: navigation, search

As ModEnc grows, it becomes more and more apparent that certain guidelines need to be established to make sure all pages have a unified look, and ModEnc doesn't suffer from messy and ugly articles.

Although an ugly contribution is better than no contribution, always think about how you would like to see the pages presented to you - the answer is most certainly not "one bigass block of text with no formatting".

There is an extra template to mark pages which do not adhere to these rules; pages marked with these template are automagically placed in Category:Cleanup. Pages in that category should be cleaned up as soon as possible.


Basic Content Guidelines

No Nicks

This is not a fucking forum. All revisions are marked with their author, if the author is logged in. If you want your name associated with content on ModEnc, register and log in. Don't place your name in the content as a signature. The only thing this will lead to is that either the name is edited out, or the whole section is re-written so you can't claim authorship any more.
Through the activation of on-page crediting, the signing within a page has also largely become redundant - the footer below every page will show who wrote the current revision, and on who contributed to the page before. If there are more than 5 different people to credit, the last link will lead to a separate credit page.


Note that unchanged, included tutorials are an exception to the signing rule; they should carry the original author in their headline. However, they should be re-written into real, ModEnc-own pages asap.

No "Download the Guide"

What's the use of documenting every flag on ModEnc if you tell the reader to go get the Guide instead? It's largely outdated, inflexible, inexpandable, unmaintained and partly even wrong. Due to our recent additions, almost every information found in the Guide is available on ModEnc as well, and in many cases it's already updated with newer, better information. There is no need to send the user to get the Guide. Simply link him to the appropriate ModEnc page.

Preview

We all make mistakes. Especially in long editing sessions, both D and I had to re-edit a just-saved page often enough just because we made a simple typo or forgot the category. However, try to avoid it. We don't do it every time, either. Preview your page. Again and again and again. When you think you're done, preview it and proofread the entire preview-output. When you can't find any more mistakes, save. And don't fucking dare re-editing the page after saving just to put your name in it. Mr. Alеx05 did that so excessively that I had to put his name into the spam filter so he couldn't save anything containing the string "Alеx05" anymore. Had I not done it, we'd probably have a thousand revisions today whose only change was "Alеx05". ¬_¬
I will not hesitate to filter anyone who tries this again. Especially not after this guide was published.

Style

Unless it is explicitly stated in this guide, you should refer to Wikipedia's Manual of Style for specific stylistic guidelines.

Dialect of English used

If you are starting a new article, feel free to pick whichever dialect suits you better, but don't mix them together. If an article already uses British/Commonwealth English, try to use that in your edits. If it uses American English, try and use that. Do not edit simply to replace one with the other. It's frowned upon in Wikipedia, and there is no reason to handle it differently here.


Content

Pimp your Content

Yes, especially D is a friend of basic, black and white layouts, and many newbies simply write their text and save. Nevertheless, the MediaWiki engine enables you to further structure your content and create beautiful pages like I do. ;) Sure, it's not the non-plus-ultra in page design, but notice how the simple addition of a few colors and the borders and different background-colors I added to the table ease the reading enormously (compare to DeeZire's pre-rewrite version - my page is five times as long and includes more information, yet it is a hundred times easier to read).
A few tools you can use to improve your content are:

Italics

Use italics to add emphasis to words.

Boldness

Use boldness to mark words as important or to emphasize warnings.

Underlining

...makes the text look like a wannabe-link. So please don't do it.

Teletyping/Monospacing

Use Monospacing to mark up flags and sectionnames, so readers know they'll find them in their files. e.g. UseOwnName, Damage, Russian, etc. Note, however, that you should not monospace them when you refer to them by name rather than as INI-objects ("the General-section" vs. "The section [General]" or "You should also play around with the MovementZone..." vs. "You should also play around with MovementZone...") - on the other hand, you can also monospace words within a text to signal they are flags at the same time, e.g. "Then you should go and adjust your weapon's Damage ..."

Code

Code blocks should either be entered with leading spaces on each line, or included in <pre> tags; the main difference is that code in <pre> tags is outputted 100% like it was entered in the page source, while code with leading spaces still interprets wiki code before outputting. The latter is important, for example, if you want to emphasize a certain part of the code.

One more thing...

I don't know about yours, but my calendar says "2024".
We're a good deal into the 21st century.
So please, please, don't torture us with 1980's markup like *this*, _this_, THIS or <this.ini>.
We've got the way cooler this, this, this and this.ini by now. ;)

Page Foreground

Referencing

Link, link, link. It costs you only four additional characters to turn a word into a link, but it can make the difference between a newb giving up and a newb understanding. So link. Don't go overboard with it, but as a general rule, all mentioned flags should be linkified the first time they occur, as well as games, files, sections etc.
Also never forget that you can and should link even if the target page does not exist yet. Not only will the link automatically be turned into an edit-link, but if enough links come together, pages will also be put on the Wanted Pages page.

Headlines

Nouns in headlines should be started with a capital letter, just as the first word. All other words start with a small letter. No punctuation either. Teletyped text should be bolded to keep it in sync with the rest of the headline. These rules can be bent if there's a particular reason against them (e.g. first word is a filename).
Make use of the levels generated by headlines. And watch if their results fit what you were trying to you. If you have =Headline A=, ==Headline B== and =Headline C=, Headline B will be a child of Headline A, while Headline C will be A's sibling. This will espcially be evident in the TOC and in the headlines' markup. On this very page, for example, I use level 1 headlines for the main sections and was forced to use level 3 headlines for the sub-sections, because the additional horizontal lines of level 2 headlines tore the page layout apart.

See also

If you know there are other topics/pages/places that are in some way connected to a page, create a "See also" section below the content and put in it an unordered list of additional links. These links can be both internal and external, for example to further reference pages, tutorials or pages describing certain hacks which use the current flag. The "See also" section should be on the highest possible level in section hierarchy, meaning either = or ==, depending on what your main headlines use.
=See also=
*[[Link 1]]
*[[Link 2]]
*[http://wwway-more-links.cnc]

Page Background

Use Templates

We have a hell of a lot of templates already, from simple ones to ease markup, over messages to inform the reader, to complex ones creating navigational elements. Read the templates page at least once, so you know what you're missing. ;)

Categorize

The MediaWiki engine as a simple, yet powerful categorization system, and with a page-count of over 2500 by now, it is in fact the only thing next to name-guessing that can quickly get the reader to a page. Many categories are added automatically by templates, like Category:INI Flags or Category:Obsolete. However, more specialized categories like Rules(md).ini Flags or Bugs and Errors need to be set manually - and it's those categories that help people find the exact thing they're looking for. Because, seriously: It's easier to find UndeploysInto if you just have to look through all BuildingTypes Flags rather than trough all INI Flags - or even all pages, if it's not an INI flag.
Oh, and don't panic if you do categorize and the link shows up in red. That just means there is no text on the category-page itself, pages still get categorized on it just fine.

Flag before Section

When an expression can refer to both a flag and a section name, the flag always has the higher priority. The page gets a proper flag header, the flag gets explained, and then, under a new heading, the section gets explain, headline either being =<tt>'''[Name]'''</tt>= or =As a Section=.

Association first

Think of Cost. What do you think of? Unit cost, right. Did you even know it's also a multiplier in two sections?
This example shall teach you one thing: Association always comes first. If an expression is strongly associated with a certain meaning, it gets the page to that expression. A second meaning can be attached with the {{meanings}} template. If there are three or more meanings, or the meanings are equal in their importance, set the main expression page up as a disambiguation page (example here) and name the linked-to pages appropriately.

Additional Pages

If you create anything that doesn't derive it's name from something else, like a flag or a section, simply name it as simple and obvious as possible - ModEnc:Templates is a good example. Or Selling Gives Free Unit Bug. But since almost anything goes, monsters like my very own The Ultimate "Pages I'd like to see on ModEnc but am too lazy to create myself" Wishlist are just as possible. Just make sure they're accessable through links and categories, or nobody will ever be able to reach your page.
When naming your page, stick to one of these three standards:
Full capitalization: Capitalize the first letter of every word.
Strong capitalization: Capitalize the first letters of everything except for articles, pronouns etc.
Noun capitalization: Capitalize the first letters of Nouns only.
Whatever you choose, be consistent with it - a title like "The history of CnC On ModEnc" is not only butt ugly, but also impossible to "guess" for outsiders if you forgot to categorize (despite our warnings :P).

TOC

The moment you have three or more headings, the Table Of Contents block appears. Don't accept this as unchangeable.
__NOTOC__ allows you to turn it off, no matter how many headlines you have.
__FORCETOC__ allows you to turn it on, no matter how many headlines you have.
__TOC__ allows you to position it - the block will appear where you put __TOC__.

Naming Conventions

Super Weapons

Super Weapons in headlines, super weapons within the text; with a space in between and no special capitalization. That's the way it happens in the comments, and therefore that's the way we'll do it.

RockPatch

pd, on the RTB homepage, clearly references the patch without a space. Also, since it's a name, both the R and the P are capitalized.

The Guide

When referencing DeeZire's Red Alert 2 and Yuris Revenge INI Editing Guide as "The Guide", both the T and the G are capitalized. When referring to it as "Guide", with a "the" before it only for grammatical reasons, the "the" stays small (e.g. "ever since DZ published The Guide ..." vs. "the Guide was wrong again ..."). In both cases, on first occurance, the term should be linked to either DeeZire's Red Alert 2 and Yuris Revenge INI Editing Guide or The Guide.

File Names

File names, if capitalization is not important, should be all lower-case. If the filename is case-sensitive, the original capitalization should be used. If referring to a file that was "MDed" later, "md" should be added in brackets to the name, at the appropriate position (e.g. rules(md).ini to refer to both rules.ini as well as rulesmd.ini). Alternatively to standard brackets, curly crackets can be used, as we did on the main INI-files pages. Remember that pages are named for their un-MDed versions, meaning you have to use piped links to link to them - [[rules.ini|rules(md).ini]], for example.

File Extensions

File extensions should either be noted in the dotExtension format, i.e. .ini for INI-files, for example, or in the just demonstrated extension-in-all-caps format, e.g. INI.

Naming of INI Content

The rules' comments refer to the areas headed by expressions in brackets as "sections", and to the argument-based variables in these areas as "flags". Therefore, we speak of "flags" and "sections" as well.