Doomsday Wiki:Wiki contributor guidelines

From Doomsday Wiki
Jump to: navigation, search

For a quick-start guide into wiki editing, see [1].

If you plan to make lots of contributions to the wiki, please read the guidelines described in this article carefully.

Examples

A select few articles have been marked with the {{exemplary}} tag to serve as examples of good documentation style and practices. Before doing anything, check these out (both appearance and source).

New articles

The name of the article should not use unnecessary abbreviations. For example, "OGLNotAccel" is not a good name. "OpenGL not accelerated" is better. The article names are listed in the index, and it should be possible to understand its meaning just be reading the name. Don't capitalize letters in the name unnecessarily (i.e., only capitalize proper nouns).

Do not use "the", "a", or "an" in the beginning of article names.

Stubs

If after you've created a new article and it is not yet fully completed – perhaps some details or sections are missing – you should add the {{stub}} marker to the top of the article:

{{stub}}

This will add it to the list of stub articles. It may be that another contributor is in a better position to expand your article so that it is "complete".

Links

The more links you have to other pages in the wiki, the better. The minimum requirement is that every first instance of a relevant term (Doomsday, DED, etc.) is linked to its corresponding pages in the wiki. Don't be afraid to link the other instances, too.

Don't be afraid to link terms that haven't yet been created. By creating broken links you are signalling to other contributors what new articles are needed. A link to the broken links/wanted pages is shown in the Doomsday Wiki:Community Portal.

Creating redirection pages is encouraged, so that linking is easier without having to specify alternate text for the link when writing the article. However, note that the plural "s"/"es" suffixes should not be handled with rediretion. Instead, do this:

[[line type]]s

The wiki shows the link correctly.

Using the Main namespace

Place all articles in the Main namespace. Special articles that refer to the wiki itself should be placed into the Doomsday Wiki/Help namespaces.

Categorizing articles

Assigning the proper categories to articles is very important because it is one of the most important ways of navigating the content of the wiki. Categories themselves should be organized into a hierarchy to facilitate navigation. In general, if an article belongs to a subcategory, do not add it also to the parent category.

The same content should never be duplicated in many articles. However, the same article can belong to multiple categories, allowing for flexible organization.

Choosing the categories

The wiki contains several hierarchies of categories. The Table of Contents is organized according to these hierarchies. The guideline is that for each article, select at most one (sub)category from each hierarchy. In some cases it is suitable to select multiple categories from the same hierarchy (e.g., XG + DED). Try to never include an article both in a subcategory in that subcategory's parent category, since that is redundant and clutters up the index of the parent category.

  • User's Guide
  • Author's Guide
  • Programmer's Guide
  • Engine (top level)
    • UI
    • Console
    • etc.
  • Editing (top level)
    • XG
    • DED
  • Resources (top level)
    • Models
  • Networking (top level)
    • Multiplayer (does this make sense? --skyjake)

For example, an article could be placed in the User's Guide, Console, and DED categories. In this case, putting it also in the Engine and Editing categories would be redundant.

Category maintenance

If a category contains too many articles, consider breaking it up into subcategories. Too small categories should be merged into an appropriate larger category.

Category names should be capitalized like all titles and headings. That is, no unnecessarily capitalization. For example, "XG line class".

Other examples:

  • "OpenGL" (capitalization according to convention)
  • "Author's Guide" (this is the name of the guide, hence capitalized)

The article tags (stub, breakdown, cleanup, exemplary) automatically place the article in the respective maintenance category.

Indices

The automatically generated category indices should be preferred to manually "moderated" indices, as they are updated automatically whenever articles are added to/removed from categories. However, the highest level indices (e.g., the Main Page) should always be moderated.

If the category name happens to be included in the beginning of an article name, for example XG refs in the XG category, then you should use the MediaWiki sort key feature to make the articles better sorted in the category. Only apply this when necessary, though, not for all categories.

Signatures

Do not add signatures to the article content itself. They have no value for most readers, and the wiki tracks this information in the version history automatically. If the situation truly requires the use of a signature, use MediaWiki's --~~~ and --~~~~ tags.

Matters of style

High-quality documentation has a consistent style. This makes it easier to read. Here are some rules you should keep in mind and follow whenever possible:

Typefaces

  • Use the italic style (i.e., ''italic style'') for the first occurence of the term that an article is about. For example, in the XG article, the terms "XG" and "Extended General Line and Sector Types" are in italic style.
  • File names and paths should be bolded, for example /usr/bin/doomsday and Doomsday.exe.
  • When mentioned inside article text, command line options and console variables should be in italics. For example: "The -file option is used for loading files. The rend-camera-fov variable controls the FOV angle."
  • Source code, script source, and console commands should be enclosed within <code> tags, for example: "The listcmds console command lists all console commands." Alternatively, use a preformatted block (<pre> or the wikitext equivalent).
  • Use of HTML character entities such as &larr;, &rarr;, and &ndash; is encouraged.

Titles and headings

  • Page titles should be complete and meaningful. Use spaces. For example, "BarrelMonster" is a bad page title, but "Creating a Barrel Monster" is a good one. This makes category indices (which only show the titles) much more informative.
  • Section and subsection headings should not use the title case. That is, only capitalize the first letter of the heading, and any proper nouns. See the headings in this article for examples.

Space

  • If you find yourself using parentheses (you shouldn't), do not put extra space inside parentheses, like this:
    • An example of ( bad ) parentheses having extra space ( like this ).
  • Do not use more than one empty line to create paragraph breaks. Use (sub)sections, indentation, and lists to create readable structure, not empty space.

Article structure

  • Category links should be placed in the bottom of the article, since that is where they appear when the page is viewed in normal mode. Use categories liberally (but not too liberally); readers will appreciate it when they are looking for a particular detail.
  • If possible, articles should have the following structure:
    1. Stub link, if needed.
    2. Maintenance links ("breakdown", etc.).
    3. Do not use a redundant heading at the top of the article which matches the page name.
    4. Brief overview of what the article is about, without a heading (the page title is the heading for this text). This is where the reader decides if the rest of the article is of interest.
    5. Content of the article, divided into sections and (sub)subsections.
    6. A section called "See also" with links to any other pages of interest.
    7. A "Footnotes" section, if any <ref> tags were used.
    8. An "exemplary" link, if appropriate.
    9. Categories the article belongs to, one per line.

Do not...

  • DO NOT use the __NOEDITSECTION__ special tags to prevent section edit links from appearing. Editors find these links quite useful.
  • DO NOT put a "breadcrumb" path in the top of the article. Proper categorization makes these redundant, and they are just extra work to maintain. If you really want to create hierarchical pages (like "Top / Something / Small detail"), then use the MediaWiki subpages feature. However, carefully consider using categories instead!
  • DO NOT use the "See also" section as a breadcrumb, either.
  • DO NOT use horizontal lines (----) unless there is a very good reason to. Remember, there are better solutions like indentation, subsectioning, blockquotes, italic text, etc.

Spelling

In this wiki, we prefer to use U.S. English spelling. For example, "color", "categorize".

Articles marked for cleanup

The {{cleanup}} tag should be added to the beginning of the articles that need to be clarified or that need to be fixed to more closely follow the guidelines.

"Readme" articles

The Readme category is special: the articles are generated out of the same Amethyst sources that are used for the Readme documentation included in distribution packages. While the Readme acts as a general overview, it should link to more detailed articles in the wiki. Never edit the Readme articles in the wiki; all manual changes will get overwritten when the autobuilder refreshes the wiki content.

See also