Difference between revisions of "Maintaining the Wiki"

m (Another formatting rule)
(Update template info)
Line 74: Line 74:
 
* Legacy-warning: A red box with the title "Legacy." Used on pages in the <code>Legacy</code> namespace, which is for obsolete but possibly still useful pages. Example: {{Popup-code|content=<nowiki>{{Legacy-warning}}</nowiki>}}
 
* Legacy-warning: A red box with the title "Legacy." Used on pages in the <code>Legacy</code> namespace, which is for obsolete but possibly still useful pages. Example: {{Popup-code|content=<nowiki>{{Legacy-warning}}</nowiki>}}
 
* ArticleMainTitle: A title template, used for main pages and not documentation pages (see above). Example: {{Popup-code|content=<nowiki>{{ArticleMainTitle|content=Example Title}}</nowiki>}}
 
* ArticleMainTitle: A title template, used for main pages and not documentation pages (see above). Example: {{Popup-code|content=<nowiki>{{ArticleMainTitle|content=Example Title}}</nowiki>}}
* Faq-question: You can use this template to hide information until someone clicks on the "Expand" button. It's not only useful for FAQs—you can use it to organize lots of information that might only be relevant for a few people (e.g. operating system-specific instructions). Example: {{Popup-code|content=<nowiki>{{Faq-question
+
* ArticleMinorTitle: A subheading template. Only use on pages that use ArticleMainTitle. Example: {{Popup-code|content=<nowiki>{{ArticleMinorTitle|content=Example Subheading}}</nowiki>}}
 +
* Faq-question-test: You can use this template to hide information until someone clicks on the "Expand" button. It's not only useful for FAQs—you can use it to organize lots of information that might only be relevant for a few people (e.g. operating system-specific instructions). Example: {{Popup-code|content=<nowiki>{{Faq-question-test
 +
|id=example_id <!-- Unique ID potentially used for anchor links -->
 
|title=Example title
 
|title=Example title
|answer=Example answer}}</nowiki>}}
+
|answer=Example answer
 +
}}</nowiki>}}
  
 
=== Writing ===
 
=== Writing ===

Revision as of 03:18, 14 February 2017

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

The decision to disallow user registration was made for quality assurance purposes, as the old website looked unprofessional, confusing, and was mostly outdated.

Our new approach is to only allow well known contributors to have wiki accounts. To still allow community contributions, we now have a service that automatically syncs the wiki content with GitHub. This means you can now contribute to wiki using the github workflow.

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.
  • 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

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:

Visual

Page Layout

All main pages (i.e. not documentation pages) must use the Generic-hide-summary template to remove the title and use the ArticleMainTitle template for headings.

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:
  • ArticleMainTitle: A title template, used for main pages and not documentation pages (see above). Example:
  • ArticleMinorTitle: A subheading template. Only use on pages that use ArticleMainTitle. Example:
  • Faq-question-test: You can use this template to hide information until someone clicks on the "Expand" button. It's not only useful for FAQs—you can use it to organize lots of information that might only be relevant for a few people (e.g. operating system-specific instructions). 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. Some styling is not precisely defined by English conventions, but for readability purposes we do ask you to follow a few punctuation and syntax rules:
    • Please use em dashes (—) rather than two hyphens (--) or an en dash (–) for isolating phrases in a sentence.
    • Page titles have to be properly capitalized. A guide can be found here.
    • Section headings should also be capitalized following the same rules as with page titles, except when the heading is particularly long, contains a verb, or is a full phrase.
  • 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.
  • Remember, English is not everyone's primary language.
  • When providing instructions for computer programs such as Blender, use bold text for any user interface (UI) components and names.
  • Code or directory names that are inline (part of a paragraph) should use the <code></code> tags. Non-inline code (e.g. commands) should use the Popup-code template.

Making Contributions

"Okay," you say, "I've read all these rules! Now how do I actually contribute?" It's simple, if you're familiar with Git: open an account on GitHub (if you don't already have one) and fork the repository that contains the content for this wiki. Make any changes you want, then submit a pull request to get your changes merged. The auto-deploy script runs whenever a commit is made on GitHub, so your changes should appear live within a minute or two! (Google is your friend if you need help with forking and pull requests.)


Once your contribution has been accepted, it will automatically be deployed to the wiki in a few minutes.

Files

Occasionally, you may need files uploaded to the wiki along with writing. These can be easily included in a pull request, just like text changes. Simply add a file to the repository (without the File: prefix). Spaces in the filename will automatically be converted to underscores on the wiki.