Documentation/Style guide

Overview
This page is a supplementary style guide for authoring and editing technical documentation in MediaWiki and other technical spaces. It is intended to highlight best practice and provide tips for writing clear, concise technical documentation in plain English.

For thorough coverage of general style and usage guidelines used across Wikimedia projects see the English Wikipedia's Manual of style.

English Wikipedia's Manual of style
The English Wikipedia Manual of style is the definitive style manual for English language articles on Wikipedia. This is the primary page for the style guidelines: it covers certain topics (e.g. punctuation) in detail and summarizes the key points of others, and it represents an excellent reference for anyone writing or editing technical documentation in English across Wikimedia projects.

General style guidelines

 * 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 too many strong passages, so everything is yelling and nothing ends up important.
 * Use  or italic   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. See Extension:SyntaxHighlight for details.
 * Use manual for file paths such as LocalSettings.php by writing, which will output  (also the shorter, and equivalent version of.
 * Use  for actual text the user types into an input field or as a terminal command line.
 * Or use 
 * Within and  be sure to use   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 new page, first view the source of 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
 * 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