Documentation/Style guide

This page has tips and best practices for writing pages on mediawiki.org

Writing style

 * Follow English Wikipedia's Manual of style, in particular
 * w:MOS:CAPS "Wikipedia avoids unnecessary capitalization", so use sentence case (like "Writing style" above) in page titles, section headings, table headings, and captions.
 * AVOID PASSIVE VOICE. "Extensions must be registered before they are initialized" is dead lifeless prose that leaves it unclear who is doing the actions. Instead
 * Talk to the reader! "You need to register your extension", "When you update your wiki", etc. In a tutorial, "We next register a callback"
 * Identify the agent doing the work if it's not "you" the reader. "When the user clicks Save", "When an editor adds the parser tag to a page", "When MediaWiki core runs the extension's setup function".
 * "Press Save", NOT "Hit Save".

Markup

 * Don't overuse strong (bold)emphasis, start with regular (italic) emphasis
 * Also use  for variables like message-key-name and sample names like My page title . Don't use punctuation such as , readers don't know the angle brackets are noise and will type them.
 * Use  for computer instructions, including wikitext markup.
 * Or use the  tag if it's more than a few words; you can use   attribute to have syntax-colored code inline in a paragraph.
 * Use  for file paths (file names are not computer code!)
 * Use  for actual text the user types into an input field or as a terminal command line.
 * Or use
 * Within for variables and sample names so users know what to replace.
 * Sadly you can't use italic in the middle of a  source code block, so you have to fall back to YOURPASSWORD or The_page_title.

Useful templates
mediawiki.org pages are template-heavy, both to deliver consistency and to ease translation. Assume there's a template for whatever you're typing.
 * ApiEx for api.php URLs
 * Api help to transclude generated API documentation
 * git file to link to source code
 * for IRC link
 * Key press for Ctrl+Shift+I
 * wg for global variables

You use many of these with TNT or TNTN so they internationalize.

And of course interwiki links:
 * for tasks and project tags
 * mail:wikitech-l for mailing lists
 * to English Wikipedia articles
 * for details about the WMF cluster.

Internationalization and localization
All pages on mediawiki.org are candidates for translation into multiple languages. mediawiki.org is a multilingual wiki, it uses the Translate extension to present alternative translations and manage the translation of pages.

Tips:
 * If a page has been translated, then click 'Edit source' to edit the entire page. The translation tag markers around section headings confuse section editing, and VisualEditor does not understand the, , and tags.
 * You can copy and paste existing idioms, but if in doubt leave out all translation machinery and just write English