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".
 * "Click Save or press enter", not "Hit Save or Enter".
 * We assume a basic level of familiarity with entering commands in a terminal. So write "Enter the following commands in a terminal window: " or "Enter  in a terminal" not verbiage like "open a UNIX shell and type the following commands and then press the Enter key."   If.

Markup

 * Don't overuse strong (bold) emphasis ; instead start with regular (italic) emphasis , or use a Caution, Note, or Warning template without any emphasis. In general  pages have wound up with too many strong passages, so everything is yelling and nothing ends up important.
 * 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 its   attribute to have syntax-colored code inline in a paragraph.
 * Use  for file paths such as LocalSettings.php (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. When you create a page, view the source or copy a similar page to pick up e.g. the Extension infobox or MW file box.
 * ApiEx for api.php request URLs
 * Api help to transclude generated API documentation
 * caution, note, and warning boxes.
 * class doclink and file doclink to link to MediaWiki core's generated documentation]
 * git file to link to source code
 * for IRC link
 * Key press for, e.g. Ctrl+Shift+I
 * MW file for a box with info and links for a file in MediaWiki core
 * tracked for the related Phabricator task
 * RestOfVariableName 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