Documentation/Style guide

From MediaWiki.org
Jump to: navigation, search

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

Writing style[edit]

  • 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:<source lang=bash>$ command...</source>" or "Enter <source lang=bash inline>one command</source> in a terminal" not verbiage like "open a UNIX shell and type the following commands and then press the Enter key." If <source lang=bash> highlights wrong, use <code>

Hooks and events[edit]

As docs/hooks.txt says, a hook is the "clump of code and data that should be run when an event happens" in the client(s) of an event such as PageContentSave.

Markup[edit]

  • 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, www.mediawiki.org pages have too many strong passages, so everything is yelling and nothing ends up important.
  • Use <var> or italic '' for variables like message-key-name and sample names like My page title . Don't use punctuation such as <YOURPASSWORD>, readers don't know the angle brackets are noise and will type them.
  • Use <code> for computer instructions, including wikitext markup.
    • Or use the <source lang="computerlanguage">...</source> tag if it's more than a few words; you can use its inline 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 {{manual|LocalSettings.php}}, which will output LocalSettings.php (also the shorter, and equivalent version of [[Special:MyLanguage/Manual:LocalSettings.php|LocalSettings.php]].
  • Use <kbd>...</kbd> for actual text the user types into an input field or as a terminal command line.
    • Or use <source lang="text">...</source>
  • Within <code> and <kbd>...</kbd> 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 lang="foo">...</source> source code block, so you have to fall back to YOURPASSWORD or The_page_title.

Useful templates[edit]

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.

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

And of course interwiki links:

  • [[phab:]] for tasks and project tags
  • [[mail:wikitech-l]] for mailing lists
  • [[w:en:foobar]] to English Wikipedia articles
  • [[wikitech:foobar]] for details about the WMF cluster.

Internationalization and localization[edit]

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 As of July 2015 VisualEditor does not understand the <languages>, <translate>, and <tvar> tags.
  • You can copy and paste existing idioms, but if in doubt leave out all translation machinery and just write English

See also[edit]

External links[edit]