MoodleDocs:Style guide

Describing the location of items

Examples:

• The setting 'Language autodetect' in 'Site administration > General > Language settings' (with the nav trail in italics).
• In the Boost theme, we have a course index and course navigation.
• 'Course navigation > Participants' then from the dropdown select Groups
• 'Course navigation > More > Course reuse'.
• From the user menu (top right) select Preferences then Notifications preferences.
• 'Course navigation > Grades'.

Categories

A category is an index of documentation pages.

• A page can be added to a category by typing [[Category:Category name]], for example [[Category:Site administration]], at the bottom of the page. Many templates automatically categorise pages using the template, for example [[Template:Forum]] categorises pages into Category:Forum.
• For linking to a category you have to add another colon like so: [[:Category:FAQ]] which will show as Category:FAQ.
• Categories lists all Moodle Docs categories. This can be found in the Toolbox Special pages link.
• For further information about categories and how they work in MediaWiki, please refer to the Wikipedia:Categorization.

Screenshots

• You are encouraged to illustrate documentation with screenshots. Please use the official Moodle sandbox demo site, or any other site or course using one of the standard themes, and ensure that the screenshot focuses on the specific feature.
• Screenshots should be preferably PNG format, with 72ppi resolution, and maximum width 800px.
• To fit more into a screenshot, select a smaller text size for the web page via the View > Text size menu in your web browser.
• Screenshots should be uploaded using the Images icon in the editor.
• Please name screenshots using the convention 'version number + descriptive name such as page heading' e.g. 404backupsettings.png
• Fill in alt text but no caption, not thumb, left aligned.
• Ideally add a border 1px grey (if no grey background).

Templates

• In MediaWiki, a template is a page which can be inserted into another page. For example, the Moodle Docs help block on this page is a template.
• A template may be added to a page by typing {{Name}} for Template:Name (template names are case sensitive).
• All pages (Template namespace) lists all Moodle Docs templates.
• Please refer to the MediaWiki Template help for further information.

Moodle Docs editing tags

• Deletion - If you find any page requiring deletion, type {{Deletion}} at the top of the page. Use the page comments if necessary to state the reason for deletion.
• Update - Features increase with each Moodle version. If you find a page requiring updating, type {{Update}} at the top of the page.
• Stub - Developers and Moodle Docs administrators may add a new page with a {{Stub}} tag at the top, requesting help in adding content.
• You can also use the edit summary to communicate the need for more editing. For example, in the page history you might see: "Added section, needs more work, see page comments".

PHP syntax highlighting

• To highlight PHP syntax, enclose the code in tags:

<syntaxhighlight lang="php">... Some PHP code here...</syntaxhighlight>

That will be rendered as:

<?php
require_once(dirname(__FILE__) . '/../../config.php');

$cmid = required_param('cmid', 0, PARAM_INT);
if (!$cm = get_coursemodule_from_id('quiz', $id)) {
    print_error('invalidcoursemodule');
}
...

• For long code examples you can even add line numbering like so:

<syntaxhighlight lang="php" line>... A lot of PHP code here...</syntaxhighlight>

That will be rendered as:

<?php
require_once(dirname(__FILE__) . '/../../config.php');

$cmid = required_param('cmid', 0, PARAM_INT);
if (!$cm = get_coursemodule_from_id('quiz', $id)) {
    print_error('invalidcoursemodule');
}
...

• But beware, line numbering makes copying & pasting of code examples more cumbersome!

CSS syntax highlighting

• To highlight CSS syntax, enclose the code in tags:

<syntaxhighlight lang="css">... Some CSS code here...</syntaxhighlight>

• Example:

.que .info .grade { display: none; }

• You can see many examples of this in the Quiz FAQ Doc page.
• See also the documentation on Code syntax highlighting that uses the GeSHi (Generic Syntax Highlighter) filter.