Help:Conventions
From DmWiki
In order to keep our wiki consistent, we ask that if you are going to write or edit an article, you keep in mind a few simple conventions. If you break one of these it's no big deal; someone will probably come along and fix it for you, but it will save us all time and effort if these conventions are followed from the start.
If you are unsure of something, or need help with the wiki, then please bring the matter up on the DmWiki section of the DevMaster forums (http://www.devmaster.net/forums/).
| Table of contents |
Article Titles
Article names in the wiki are case-sensitive: if the article is titled "Scene Graph", then making a link to "scene graph" won't work. Only the first character can have its case changed (a link to "scene graph" will go to the article Scene graph).
In order to avoid problems with links, article titles should be all lowercase except the first character. This is probably the most important convention of all. Of course, this rule does not apply if the article name is an acronym, such as Direct3D, or the name of a person.
The other rule about article titles is that article titles should be singular in most cases. For instance, create an article called "Sprite", not "Sprites". The reason for this is that when the article is linked to, a plural 's' can easily be added if necessary. For instance, the sentence "Billboards are usually created using sprites" can be written in wiki markup as:
[[Billboard]]s are usually created using [[sprite]]s
Sometimes it is fine to have a plural article title, if the term is usually used in plural - for example, vectors and matrices.
Finally, article titles should try to avoid -ing words when possible. For example, use "Rasterization" rather than "Rasterizing". This is a less strict rule, and is only there because the -ing words sound less professional. In many cases it's not possible to avoid the -ing words, and that is no problem.
Writing Style
When writing articles, try to avoid the first and second person. That is, try to avoid using "I", "me", or "you". Articles should be impersonal; they should sound like a piece of scholarly writing, not like a conversation. By all means, make articles interesting and (where appropriate) funny, but do not make them informal.
When writing about AI or algorithms, too many books and tutorials are specific to Microsoft Windows or some other particular platform. Articles should be written as independent of platform, API, and language as possible, except when they deal specifically with some piece of software or technology. Remember, not everyone uses the same coding environment!
Links
Similiarly to article titles, links should usually be lowercase. Normally, links will appear as ordinary words in a sentence, such as "Most 3D APIs use transformation matrices." In this case, the link to "matrices" should not be capitalized. Of course, the link to "API" is capitalized because API is an acronym.
Math
The DmWiki uses the following conventions for writing mathematical equations:
- Scalars (ordinary numbers) are lowercase and in italic.
- Vectors are lowercase and in bold.
- Matrices are uppercase and in bold.
For example, in the equation
the values A and B are matrices, n and p are vectors, and d is a scalar. These conventions should be followed both in text and in equations. In text, you can use double quote marks to make italics, e.g. ''d'' makes d, and triple quote marks make bold, e.g. '''A''' makes A. In equations, things are italic by default, and you can use the \mathbf command to make them bold.
Grammar
It is generally appreciable and encouraged to utilize grammar and proper structure when writing an article. It is frowned upon, therefore, to write utilizing shorthand acronyms that are uncommon to the topic of game development. For example, the acronyms API, OS, GDI, and GFX are acceptable use. However, other acronyms may be questionable, specifically lol, omg, or acronyms in relation to games such as HL, L2, SC, etc, as it creates a potentially unfriendly environment by making others incapable of understanding what is being written. It is oft appreciable (though not required) also to provide the meaning behind an acronym. For example, GLSL is Graphics Library Shading Language, the name given to OpenGL's own proprietary shader language.
