Difference between revisions of "Maintaining the Wiki"

m (Use underline instead of italics for part about user reg)
m ("Transclude" instead of "use")
Line 64: Line 64:
 
==== Page Layout ====
 
==== Page Layout ====
  
All ''main'' pages (i.e. not documentation pages) must use the <code>Generic-hide-summary</code> template to remove the title and the <code>ArticleMainTitle</code> template for any headings. These pages should not have a page title unless necessary. For example, the [[Download]] page's heading says
+
All ''main'' pages (i.e. not documentation pages) must transclude the <code>Generic-hide-summary</code> template to remove the title and the <code>ArticleMainTitle</code> template for any headings. These pages should not have a page title unless necessary. For example, the [[Download]] page's heading says
  
 
{{ArticleMainTitle|content=Get the latest version for your system!}}
 
{{ArticleMainTitle|content=Get the latest version for your system!}}

Revision as of 21:31, 13 September 2016

A while ago we switched from supertuxkart.sourceforge.net to simply supertuxkart.net. But we also made a lot more changes: a new version of MediaWiki, a new skin, and, perhaps most importantly, no more open user registration.

Why? Well, there were a number of reasons. There was no quality assurance on the old wiki. The problem with running a website using wiki software is that it's still a wiki: anyone can edit it. If we had maintained a separate wiki, this might not have been quite such a problem, but as a result, the entire website looked unprofessional, confusing, and outdated.

Our new approach is to only allow a few select people have wiki accounts. We now have a service that automatically syncs the wiki content with GitHub, and you can fork the repository, submit pull requests, and file issue reports—all without allowing wiki account creation. This page covers how YOU can start contributing to keep the wiki organized, friendly, and up-to-date.

MediaWiki Markup

This website is powered by MediaWiki. Pages are written in MediaWiki's own markup language. Some basic formatting information can be found here.

To maintain a the same style throughout the wiki, as well as preserve mobile-friendliness, we do require a few restrictions on what markup you may use.

  • Use only level-2 headings and below (e.g. == Level 2 ==). Level-1 headings are for page titles only.
  • Use logical heading order.
  • When using tables in documentation, be sure that you are using the wikitable class:
  • Use packed MediaWiki galleries for images to preserve mobile-friendliness, unless images are extremely small:
  • To maintain readability of code,
    • Put an empty line above and below headings.
    • Put a space between heading markup (==)and headings.
    • Put an empty line above and below templates, unless avoiding whitespace
    • Avoid use of HTML wherever possible. Use empty lines to create line breaks rather than <br /> tags.

Maintaining Documentation

While most programming documentation uses Doxygen and therefore is not maintained on the wiki, all the artists' documentation is on this website, linked from the Art Portal.

Format of Artists' Tutorials

It's important to have a standard format for tutorials. Every tutorial has an index page titled "Making <Art type>" (e.g. Making Tracks). This page uses the Popup-prerequisite template, followed by a short introduction, a level 2 heading "Contents," and a series of bullet points with links to various chapters of the tutorial. Optionally, tutorials may have another level-2 heading and series of bullet points linking to appendices.

Modular Concept

Wherever possible, articles should not be tied to a specific tutorial. Materials, Texturing, and Special Effects are examples of articles that are part of multiple tutorials. On the other hand, keep content specific to a certain type of artwork in separate articles. These articles should have titles prefixed with the name of the tutorial (e.g. Making Tracks: Ideas and Concept Art).

Under certain circumstances, you may come across a subject which is partially relevant for one tutorial, and fully relevant for another. In such cases, you should write a full article about the subject for the tutorial to which it is most relevant, then surround the content relevant for both tutorials in <onlyinclude></onlyinlcude> tags, and transclude the content into an article of the less related tutorial.


An example of the above circumstances is lighting. It is most relevant for the Making Tracks tutorial, but the Making Library Nodes tutorial should also include a section about point lights and volumetric lighting. For this case, I wrote a full article about lighting for the track-making tutorial, Making Tracks: Sky and Lighting. However, I surrounded the section on point lights and the section on volumetric lighting in <onlyinclude></onlyinclude> tags, and transcluded these sections into the Making Library Nodes: Lights page, using the following markup:

Art Portal Navigation Template

We provide a template to be placed at the bottom of all art-related documentation. Please use it—it greatly improves navigation between articles. Add it to the bottom of any artwork documentation pages you create:

Style

While most of the visual style is provided by the wiki skin, some parts are your responsibility to get right.

Visual

Page Layout

All main pages (i.e. not documentation pages) must transclude the Generic-hide-summary template to remove the title and the ArticleMainTitle template for any headings. These pages should not have a page title unless necessary. For example, the Download page's heading says


Get the latest version for your system!

instead of "Download." It's obviously the download page—a title would be redundant.

All documentation pages, like tutorials, guidelines, etc. use standard MediaWiki formatting, with the exception of any templates or pictures (which should use packed galleries, as mentioned above).

Templates

We provide several templates ready-to-use for articles. Please use them. They are:

  • Popup-warning: A blue box with the title "Info." Example:
  • Popup-code: A dark gray box with the title "code." Example:
  • Popup-prerequisite: A orange box with the title "Prerequisites." List links to articles that should be read before starting a tutorial using an unordered list inside this template. Example:
  • Legacy-warning: A red box with the title "Legacy." Used on pages in the Legacy namespace, which is for obsolete but possibly still useful pages. Example:

Writing

It's important to keep the quality of contributions up. Better contribution moderating is one of the goals of the switch to GitHub. Here is a list of rules you need to follow:

  • You must follow English grammar rules to the best of your ability. If you are unable to, feel free to send in your pull requests, but we may require you to correct any issues before merging. We aren't terribly strict, but we will also willingly accept contributions to correct any mistakes.
  • Page titles should properly capitalized. A guide can be found here.
  • Write in clear, descriptive paragraphs and follow a logical sentence order. While it's useful to be concise, please spend time to make your writing completely understandable.
  • When providing instructions for computer programs such as Blender, use bold text for any user interface (UI) components and names. This improves readability and allows for experts to get through faster without confusing newbies.