Guideline template

Moodle User Interface Guidelines > Guideline template

This guideline template acts as instructions on how to write a guideline. It describes what should appear under each heading. For relevant guidelines (patterns) on pattern writing, I have referred to relevant sections in A Pattern Language for Pattern Writing.

Important points to consider that dictate much of the form of a guideline include: Single-Pass Readable, Skippable Sections and Findable Sections.

See also: Pattern Naming and Referencing Patterns, Patterns For Making Patterns Understandable

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

This is a guideline template for a Moodle Interface Guideline. Comments: developer forum thread

Problem

Describe the problem this guideline/pattern is a solution to. Imagine the situation in which a developer is when they need this guideline, and describe it as briefly as possible, but still being detailed enough to enable the reader to recognize if this guideline is what they need or not. Ensure the problem is also kept separate from the constraints of the Solution.

Example: Progressive disclosure#Problem / Pattern: Mandatory Elements Present

Context

The circumstances in which the problem is being solved imposes constraints on the solution. The context is often described via a "situation" rather than stated explicitly. Sometimes, the context is described in terms of patterns [guidelines] that have already been applied. The relative importance of the forces (those that need to be optimized at the expense of others) is determined by the context. - Mandatory Elements Present

Describe the situation/context a developer is in when they need this guideline. Do not repeat information already in the problem section.

Example: Progressive disclosure#Context

Forces: factors that affect selection

Forces: The often contradictory considerations that must be taken into account when choosing a solution to a problem. The relative importance of the forces (those that need to be optimized at the expense of others) is implied by the context. - Mandatory Elements Present

List all the points that appear in the Context that affect the decision. These often appear as points for or against the Solution. Formulate them so that they are independent of the solution and just relate to the problem. This is to make it Single-Pass Readable.

Example: "Administrators need to 'lock' the show/hide button [of progressive disclosure] because on some sites the functionality is needed by everybody"

becomes

"Some functionality that is rarely needed on some Moodle sites may be always-required basic functionality on other sites."

Visible Forces

Solution

Image 1: Screenshot demonstrating the subject of the guideline, including the different states or the sequence included in a single image

Illustrate the solution so that it is understood as quickly as possible.

Explain how the forces are alleviated by the solution. Explain the ultimate benefits/goals reached by applying the solution, and how the solution's different aspects help reach them.

If further explanation of the different aspects is required, add subheadings for them.

(Optional) Common mistakes

If there are common scenarios where this guideline is broken, list them here, explain why they are wrong and how to solve these issues.

Examples and implementation

As per A Pattern Language for Pattern writing, there should be as few examples here as possible. List one or two here and link to a separate Development:[GuidelineName] Examples and Code Samples page.

Patterns:

• Running Example
• Code Samples
• Optional Elements When Helpful

Example title

Image 1: Screenshot demonstrating the example of the guideline, including the different states or the sequence included in a single image

Refer to how the points in the Solution have been fulfilled

Further examples and code samples: (link to) Development:[GuidelineName] Examples and Code Samples

(Optional) Related issues in the tracker

• MDL-99999999 A ticket for fixing something in Moodle to be in accordance with this guideline
• CREATE: ticket not yet created in the tracker
• To be decided: description of issue in Moodle that are in conflict with this guideline but a clear decision has not been reached what should be done about it

Pattern: Optional Elements When Helpful

(Optional) Further information / Sources

Link to sources for this guideline. If you quote from these sources, add a link to this section from the earlier sections with the author name.

Pattern: Optional Elements When Helpful