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.

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

Further information: Mandatory Elements Present

Context

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

UI design problems are always being solved in a specific context, or situation. Sometimes, you can describe the context by mentioning the guidelines that have already been applied. It depends on the context which forces (see the following heading) are prioritized while selecting a solution.

Example: Progressive_Disclosure#Context

Further information: Mandatory Elements Present

Forces: factors that affect selection

List all the consideration that appear that affect choosing the solution. 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 the guideline Single-Pass Readable.

Forces: The often contradictory considerations that must be taken into account when choosing a solution to a problem.

Further information: Mandatory Elements Present

For example, while writing the guideline for progressive disclosure, the following force was identified:

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

To make it independent of the solution, I included only the force (problematic consideration) in it here, and moved the solution (locking the show/hide button) into the Solution part of the guideline:

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

Further information: 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

Additional information to supplement the Guideline template

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