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 work. 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 who's 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
 * 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,  English Wikipedia articles,  WMF details, etc.

Internationalization and localization
All pages on mediawiki.org are candidates for translation into multiple languages. mediawiki.org is a multilingual wiki.

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, tags.
 * You can copy and paste existing idioms, but if in doubt leave out all translation machinery and just write English